Skip to content

README.md

Latest commit

 

History

History
221 lines (168 loc) · 7.66 KB

README.md

File metadata and controls

221 lines (168 loc) · 7.66 KB

ESP32 SignalR Client Library

A complete ESP32/ESP-IDF implementation of Microsoft SignalR client, adapted from SignalR-Client-Cpp.

⚡ Optimized for ESP32

  • 🎯 Memory Efficient: ~22KB RAM (70% reduction from original port)
  • 🔧 Configurable: Kconfig options for fine-tuning
  • 🚀 Lightweight: Only 2 worker threads by default
  • 📦 Modular: Optional features can be disabled
  • 🛡️ Stable: Queue overflow protection prevents memory leaks
  • 📊 Debuggable: Optional stack monitoring for optimization

Features

  • ✅ Full SignalR protocol support (Hub connections, negotiation, handshake)
  • ✅ Auto-Reconnect with exponential backoff (similar to JS/C# clients)
  • ✅ WebSocket transport using ESP-IDF native esp_websocket_client
  • ✅ HTTP client using ESP-IDF native esp_http_client
  • ✅ JSON serialization using cJSON
  • ✅ FreeRTOS task scheduling
  • ✅ Configurable memory usage via Kconfig

Architecture

┌──────────────────────────────────────────────────────────┐
│  SignalR Core Protocol (unchanged)                       │
│  - Hub Connection, Negotiation, Handshake                │
│  - JSON Protocol, Message Routing                        │
└──────────────────────────────────────────────────────────┘
                          ↓ Abstract interfaces
┌──────────────────────────────────────────────────────────┐
│  Platform Adapters (ESP32 implementation)                │
│  - esp32_websocket_client  → esp_websocket_client        │
│  - esp32_http_client       → esp_http_client             │
│  - JSON Adapter            → cJSON                        │
│  - Scheduler Adapter       → FreeRTOS                     │
└──────────────────────────────────────────────────────────┘

Requirements

  • ESP-IDF >= 5.0.0
  • ESP32, ESP32-S2, ESP32-S3, ESP32-C3, or ESP32-C6
  • C++ exceptions enabled: CONFIG_COMPILER_CXX_EXCEPTIONS=y

Installation

Using ESP Component Registry

dependencies:
  verdure/esp-signalr: "^1.0.0"

Manual Installation

cd your-project/managed_components
git clone https://github.com/maker-community/esp-signalr.git verdure__esp-signalr

Quick Start

Basic Connection

#include "hub_connection_builder.h"
#include "esp32_websocket_client.h"
#include "esp32_http_client.h"

// Create connection
auto connection = signalr::hub_connection_builder::create("https://your-server.com/hub")
    .with_websocket_factory([](const signalr::signalr_client_config& config) {
        return std::make_shared<signalr::esp32_websocket_client>(config);
    })
    .with_http_client_factory([](const signalr::signalr_client_config& config) {
        return std::make_shared<signalr::esp32_http_client>(config);
    })
    .build();

// Register message handler
connection.on("ReceiveMessage", [](const std::vector<signalr::value>& args) {
    ESP_LOGI("SignalR", "Received: %s", args[0].as_string().c_str());
});

// Start connection
connection.start([](std::exception_ptr ex) {
    if (!ex) {
        ESP_LOGI("SignalR", "Connected!");
    }
});

// Send message
std::vector<signalr::value> args;
args.push_back(signalr::value("Hello from ESP32!"));
connection.invoke("SendMessage", args);

With Auto-Reconnect (Recommended)

#include "hub_connection_builder.h"

// Create connection with automatic reconnect (default delays: 0, 2, 10, 30 seconds)
auto connection = signalr::hub_connection_builder()
    .with_url("wss://your-server.com/hub")
    .skip_negotiation()  // Skip negotiation if WebSocket-only
    .with_automatic_reconnect()  // Enable auto-reconnect
    .build();

// Or with custom reconnect delays:
// std::vector<std::chrono::milliseconds> delays = {
//     std::chrono::seconds(0), std::chrono::seconds(1),
//     std::chrono::seconds(5), std::chrono::seconds(15)
// };
// .with_automatic_reconnect(delays)

// Handle disconnection
connection.set_disconnected([](std::exception_ptr ex) {
    ESP_LOGW("SignalR", "Disconnected, auto-reconnect active...");
});

// Register handlers and start
connection.on("ReceiveMessage", [](const std::vector<signalr::value>& args) {
    ESP_LOGI("SignalR", "Message: %s", args[0].as_string().c_str());
});

connection.start([](std::exception_ptr ex) {
    if (!ex) ESP_LOGI("SignalR", "Connected!");
});

See Auto-Reconnect Guide for more details.

Memory Usage

  • RAM: ~20-30KB
  • Flash: ~50-150KB

Configuration

Basic Configuration

Add to your sdkconfig:

CONFIG_COMPILER_CXX_EXCEPTIONS=y
CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE=512

Advanced Configuration

Use idf.py menuconfig to customize:

idf.py menuconfig
# Navigate to: Component config -> ESP32 SignalR Client Configuration

Available options:

  • Worker pool size (1-5, default: 2)
  • Stack sizes for tasks (with usage recommendations)
  • Message buffer size
  • Message queue size (overflow protection)
  • Enable/disable negotiation
  • Enable/disable trace logging
  • Enable/disable stack monitoring (development)

See Configuration Guide for details.

Examples

For a complete working example, see the separate repository: esp-signalr-example

The example includes:

  • WiFi connection setup
  • SignalR hub connection
  • Message sending and receiving
  • Error handling

Documentation

Getting Started

Configuration & Optimization

Examples & Testing

Memory Usage

Configuration RAM Usage Use Case
Minimal ~12KB Memory constrained
Default ~22KB Recommended for most projects
High Performance ~32KB High concurrency needs

See Optimization Report for detailed analysis.

License

MIT License - See LICENSE file

Credits

Based on Microsoft SignalR-Client-Cpp