CloudMouse

CloudMouse SDK - Device Configuration Header

Central configuration hub for hardware variants, firmware versioning, and device-specific settings. Provides compile-time configuration management with PCB version compatibility, network settings, and device identification integration.

Configuration Categories:

• Hardware PCB version selection with power management implications
• Firmware version tracking for OTA updates and compatibility
• WiFi network configuration and Access Point settings
• Device identification macros with automatic ID generation
• Service endpoint configuration for web-based setup

PCB Version Management:

• Version 4: Legacy power logic (inverted enable signals)
• Version 5: Updated power logic (normal enable signals)
• Compile-time selection prevents hardware damage from incorrect logic
• Affects display power management and potentially other peripherals

Device Identity System:

• Automatic device ID generation based on MAC address
• Unique UUID creation for cloud service registration
• Secure Access Point credentials derived from hardware ID
• Consistent device identification across firmware updates

Network Configuration:

• WiFi requirement flags for deployment flexibility
• Access Point configuration for device setup mode
• Web service endpoints for configuration interface
• Standardized URLs for user setup experience

Usage in SDK:

• Include this header in all hardware-dependent modules
• Use macros instead of hardcoded values for flexibility
• PCB_VERSION affects power management logic in display drivers
• Device ID macros provide consistent identification across modules
• Configuration changes require recompilation for safety

CloudMouse SDK - Core System Implementation

Main system controller that orchestrates all CloudMouse components. Handles dual-core operation, event processing, and system lifecycle.

CloudMouse SDK - Core System

The Core is the heart of the CloudMouse SDK, providing:

• Dual-core task management (UI on Core 1, Logic on Core 0)
• Event-driven architecture with hardware abstraction
• System state management and lifecycle control
• Component registration and coordination

Architecture:

• Core 0: Main coordination, WiFi, event processing, system health
• Core 1: UI rendering, encoder input, display updates (30Hz)

CloudMouse SDK - Event Bus Implementation

Thread-safe event communication system using FreeRTOS queues for reliable inter-task messaging. Implements bidirectional communication channels with comprehensive error handling and monitoring.

Implementation Details:

• Uses FreeRTOS xQueueCreate for queue allocation with fixed event size
• Copy semantics for events ensure thread safety without pointer sharing
• Non-blocking operations with configurable timeout support
• Comprehensive error checking and status reporting
• Memory-efficient fixed-size allocation strategy

Performance Characteristics:

• Queue operations: O(1) constant time complexity
• Memory usage: ~5.3KB for both queues (predictable footprint)
• Latency: < 1ms for queue operations on ESP32 @ 240MHz
• Throughput: > 10,000 events/second sustainable rate

Error Conditions:

• Queue creation failure: Insufficient heap memory
• Queue full conditions: Sending task faster than receiving task
• Invalid operations: Attempting operations before initialization

CloudMouse SDK - Event Bus Communication System

Thread-safe bidirectional communication hub for inter-task messaging using FreeRTOS queues. Enables reliable event-driven architecture between Core system tasks and UI rendering tasks.

Architecture:

• Singleton pattern for global access and resource management
• Dual-queue system for bidirectional communication (UI ↔ Core)
• Non-blocking and blocking send/receive operations with configurable timeouts
• Queue monitoring and diagnostics for system health and debugging
• Thread-safe operations suitable for multi-core ESP32 architecture

Communication Flow: Core Task → sendToUI() → UI Queue → receiveFromMain() → UI Task UI Task → sendToMain() → Main Queue → receiveFromUI() → Core Task

Queue Management:

• Each queue holds up to 10 events (configurable QUEUE_SIZE)
• Events are copied into queue (no pointer sharing for thread safety)
• FIFO ordering ensures event sequence preservation
• Automatic queue overflow detection and reporting

Usage Patterns:

1. Hardware → Core: Encoder events, system state changes
2. Core → UI: Display updates, status changes, error notifications
   
3. UI → Core: User actions, configuration changes, requests
4. System-wide: Boot sequence coordination, shutdown procedures

Performance Characteristics:

• Low latency: < 1ms for queue operations on ESP32
• Memory efficient: Fixed queue size prevents heap fragmentation
• Deterministic: Bounded execution time for real-time constraints
• Scalable: Independent queues prevent cross-task blocking

Error Handling:

• Queue full conditions are detected and reported
• Failed sends return false for application error handling
• Timeout mechanisms prevent indefinite blocking
• Queue state monitoring for system diagnostics

Thread Safety:

• All operations are atomic at FreeRTOS queue level
• No shared mutable state between tasks
• Safe for concurrent access from multiple cores
• Events are value-copied to eliminate pointer races

CloudMouse SDK - Event System Core

Comprehensive event type definitions and data structures for thread-safe inter-task communication. Forms the foundation of the SDK's event-driven architecture using FreeRTOS queues.

Architecture:

• Strongly-typed event enumeration for compile-time safety
• Fixed-size event structure optimized for FreeRTOS queue transmission
• Support for numeric data, string payloads, and specialized data formats
• Memory-efficient design with stack allocation and minimal heap usage
• Built-in helper methods for common data patterns (WiFi, encoder, display)

Event Flow: Hardware/System → Event Creation → EventBus Queue → Target Task → Event Processing

Usage Patterns:

1. Hardware events: ENCODER_ROTATION, ENCODER_CLICK, ENCODER_LONG_PRESS
2. System events: BOOTING_COMPLETE, WIFI_CONNECTED, WIFI_DISCONNECTED
3. Display events: DISPLAY_UPDATE, DISPLAY_CLEAR, DISPLAY_WAKE_UP
4. UI events: DISPLAY_WIFI_CONNECTING, DISPLAY_WIFI_SETUP_URL

Memory Layout:

• Event: ~260 bytes total (4 + 4 + 252 bytes padding)
• Optimized for FreeRTOS queue efficiency
• String data uses fixed buffer to avoid heap fragmentation
• Safe for cross-task transmission without pointer issues

Thread Safety:

• All Event operations are stack-based and thread-safe
• No shared mutable state or heap allocations
• Safe for concurrent access from multiple FreeRTOS tasks
• Immutable after creation for predictable behavior