OpenRouter ESP-IDF Client

Bring the power of modern AI to your ESP32 projects! This library transforms your microcontroller into an intelligent device capable of natural language processing, real-time conversations, and smart decision-making through OpenRouter's extensive model ecosystem.

✨ Key Features

• 🚀 Complete OpenRouter Integration - Full chat completions API support
• 📡 Real-time Streaming - Token-by-token responses for interactive applications
• 🔧 AI Function Calling - Let AI models invoke your custom ESP32 functions
• 🖼️ Multimodal Processing - Handle images and audio alongside text
• ⚙️ ESP32 Optimized - Memory-efficient design for microcontroller constraints
• 🔒 Enterprise Security - TLS/SSL with certificate validation
• � 70+ AI Models - Access to GPT-4, Claude, Gemini, Llama and more

🎯 Quick Start

Installation

Add to your ESP-IDF project:

# idf_component.yml
dependencies:
  openrouter_client:
    git: https://github.com/nikhil-robinson/openrouter_client.git
    version: "^1.0.0"

Basic Example

#include "openrouter.h"

void app_main(void) {
    // Configure client
    openrouter_config_t config = {
        .api_key = "your_openrouter_api_key",
        .default_model = "openai/gpt-3.5-turbo",
        .response_buffer_size = 4096
    };
    
    // Create handle and make API call
    openrouter_handle_t handle = openrouter_create(&config);
    char response[4096];
    
    esp_err_t err = openrouter_call(handle, "Tell me about ESP32", 
                                   response, sizeof(response));
    
    if (err == ESP_OK) {
        printf("AI Response: %s\n", response);
    }
    
    openrouter_destroy(handle);
}

💡 New to the library? Start with our Basic Usage Guide for a complete walkthrough.

📚 Documentation

🚀 Getting Started

• Basic Usage Guide - Complete beginner tutorial with examples
• Configuration Guide - Menuconfig options and runtime configuration
• Error Handling - Troubleshooting and debugging guide

🔧 Core Features

• API Reference - Complete function reference
• Streaming Guide - Real-time token streaming
• Function Calling - AI-powered function execution
• Data Structures - All structs and type definitions

🎯 Use Cases & Examples

Feature	Example	Documentation
Basic AI Chat	openrouter_text_model	Basic Usage
Real-time Streaming	openrouter_text_model_streaming	Streaming Guide
Function Calling	function_calling_example	Function Calling
Image & Audio	multimodal_example	Multimodal Guide

�️ Requirements

• ESP-IDF: v5.0+ (v5.1+ recommended)
• Hardware: ESP32/S2/S3/C3 with 4MB+ flash, 320KB+ RAM
• Network: Wi-Fi with internet connectivity
• API Key: OpenRouter account required

🚀 Supported AI Models

Access 70+ models through OpenRouter's unified API:

Popular Models:

• OpenAI: GPT-4, GPT-4 Turbo, GPT-3.5 Turbo
• Anthropic: Claude 3.5 Sonnet, Claude 3 Haiku
• Google: Gemini Pro, Gemini Flash
• Meta: Llama 3.1, Llama 2
• Mistral: Mistral Large, Mistral 7B

📋 Full model list: OpenRouter Models

⚙️ Configuration

Configure via idf.py menuconfig → Component config → OpenRouter Client or see the Configuration Guide for complete details.

Key Settings

• Response Buffer: 4096 bytes (adjustable for memory optimization)
• HTTP Timeout: 30s (increase for large responses)
• Temperature: 0.7 (response creativity: 0.0-2.0)
• Max Tokens: 1024 (response length limit)

🛠️ Running Examples

cd examples/openrouter_text_model
idf.py menuconfig  # Set Wi-Fi credentials and API key
idf.py build flash monitor

📖 Need help? Check our Error Handling Guide for troubleshooting tips.

📋 Project Status

• ✅ Stable: Core API, streaming, function calling
• 🧪 Beta: Multimodal support (images/audio)
• 📈 Roadmap: WebSocket streaming, advanced caching

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Check out good first issues to get started.

📄 License & Support

License: MIT | Issues: GitHub Issues | Docs: OpenRouter API

---

Built with ❤️ for the ESP32 community