# Event System Component Specification

**Component ID:** C-EVENT-001  
**Version:** 1.0  
**Date:** 2025-02-01  
**Location:** `application_layer/business_stack/event_system/`

## 1. Component Overview and Scope

The Event System provides a publish/subscribe event bus for cross-component communication in the ASF Sensor Hub. It decouples components, enables asynchronous event delivery, and ensures non-blocking operation throughout the system.

**Primary Purpose:** Provide event-driven communication infrastructure for loose coupling between system components.

**Scope:** System-wide event publishing, subscription management, event queuing, and asynchronous event delivery.

## 2. Responsibilities and Functions

### 2.1 Primary Responsibilities

- **Event Publishing:** Accept and queue events from any system component
- **Subscription Management:** Maintain subscriber lists for each event type
- **Event Delivery:** Deliver events to all registered subscribers
- **Queue Management:** Manage event queues with overflow handling
- **Non-Blocking Operation:** Ensure all operations are non-blocking
- **Event Filtering:** Support event filtering based on criteria

### 2.2 Non-Responsibilities

- **Event Payload Validation:** Components are responsible for payload validation
- **Event Ordering:** No guaranteed ordering between different event types
- **Event Persistence:** Events are not persisted (in-memory only)
- **Business Logic:** Does not implement application-specific logic

## 3. Provided Interfaces

### 3.1 Event Publishing Interface

```c
/**
 * @brief Publish an event
 * @param type Event type identifier
 * @param payload Event payload (may be NULL)
 * @param payload_size Payload size in bytes (0 if payload is NULL)
 * @return true if published successfully, false on error
 */
bool event_publish(event_type_t type, const void* payload, size_t payload_size);

/**
 * @brief Publish an event with timestamp
 * @param type Event type identifier
 * @param payload Event payload
 * @param payload_size Payload size
 * @param timestamp Event timestamp
 * @return true if published successfully, false on error
 */
bool event_publishWithTimestamp(event_type_t type, const void* payload, size_t payload_size, uint64_t timestamp);

/**
 * @brief Publish an event from ISR context
 * @param type Event type identifier
 * @param payload Event payload
 * @param payload_size Payload size
 * @return true if published successfully, false on error
 */
bool event_publishFromISR(event_type_t type, const void* payload, size_t payload_size);
```

### 3.2 Event Subscription Interface

```c
/**
 * @brief Subscribe to an event type
 * @param type Event type to subscribe to
 * @param handler Callback function for event handling
 * @param priority Subscriber priority (higher values processed first)
 * @return true if subscribed successfully, false on error
 */
bool event_subscribe(event_type_t type, event_handler_t handler, uint8_t priority);

/**
 * @brief Subscribe with filter criteria
 * @param type Event type to subscribe to
 * @param handler Callback function
 * @param filter Filter function (NULL for no filtering)
 * @param priority Subscriber priority
 * @return true if subscribed successfully, false on error
 */
bool event_subscribeWithFilter(event_type_t type, event_handler_t handler, event_filter_t filter, uint8_t priority);

/**
 * @brief Unsubscribe from an event type
 * @param type Event type to unsubscribe from
 * @param handler Callback function to remove
 * @return true if unsubscribed successfully, false if not found
 */
bool event_unsubscribe(event_type_t type, event_handler_t handler);

/**
 * @brief Unsubscribe from all event types
 * @param handler Callback function to remove from all subscriptions
 * @return Number of subscriptions removed
 */
size_t event_unsubscribeAll(event_handler_t handler);
```

### 3.3 Event Queue Management Interface

```c
/**
 * @brief Get number of pending events
 * @param type Event type (EVENT_TYPE_ALL for all types)
 * @return Number of pending events
 */
size_t event_getPendingCount(event_type_t type);

/**
 * @brief Clear pending events
 * @param type Event type (EVENT_TYPE_ALL for all types)
 * @return Number of events cleared
 */
size_t event_clearPending(event_type_t type);

/**
 * @brief Get event queue statistics
 * @param stats Output buffer for statistics
 * @return true if statistics retrieved successfully
 */
bool event_getQueueStatistics(event_queue_stats_t* stats);

/**
 * @brief Reset event queue statistics
 * @return true if statistics reset successfully
 */
bool event_resetStatistics(void);
```

### 3.4 System Control Interface

```c
/**
 * @brief Initialize Event System
 * @return true if initialization successful, false otherwise
 */
bool event_initialize(void);

/**
 * @brief Shutdown Event System
 * @return true if shutdown successful, false otherwise
 */
bool event_shutdown(void);

/**
 * @brief Process pending events (call from event task)
 * @param max_events Maximum number of events to process
 * @return Number of events processed
 */
size_t event_processPending(size_t max_events);

/**
 * @brief Enable/disable event processing
 * @param enabled true to enable, false to disable
 * @return Previous enabled state
 */
bool event_setProcessingEnabled(bool enabled);
```

## 4. Required Interfaces

### 4.1 Time Utils Interface

- **Interface:** Timestamp generation interface
- **Provider:** Time Utils component
- **Usage:** Generate timestamps for events when not provided
- **Data Types:** `uint64_t` timestamp in milliseconds

### 4.2 Logger Interface

- **Interface:** Logging interface
- **Provider:** Logger component
- **Usage:** Log event system diagnostics and errors
- **Data Types:** Log level, message strings

### 4.3 RTOS Interface

- **Interface:** Task synchronization interface
- **Provider:** OSAL layer
- **Usage:** Mutex for subscription management, queues for event delivery
- **Data Types:** Mutex handles, queue handles

## 5. External Interfaces

### 5.1 All System Components Interface

- **Interface:** Event publishing and subscription
- **Consumers:** All system components
- **Usage:** Cross-component communication
- **Protocol:** Function calls with event data structures

## 6. Internal Interfaces

### 6.1 Event Queue Manager Interface

- **Interface:** Internal queue management
- **Usage:** Queue operations, overflow handling
- **Implementation:** Private to Event System

### 6.2 Subscriber Manager Interface

- **Interface:** Internal subscription management
- **Usage:** Maintain subscriber lists, priority ordering
- **Implementation:** Private to Event System

## 7. Static View

### 7.1 Component Structure

```mermaid
graph TB
    subgraph EventSystem["Event System"]
        Publisher[Event Publisher]
        SubscriberMgr[Subscriber Manager]
        QueueMgr[Event Queue Manager]
        EventProcessor[Event Processor]
        FilterEngine[Filter Engine]
    end
    
    subgraph Storage["Internal Storage"]
        EventQueue[Event Queue<br/>Lock-Free Ring Buffer]
        SubscriberLists[Subscriber Lists<br/>Per Event Type]
        Statistics[Queue Statistics]
    end
    
    subgraph External["External Components"]
        Components[System Components]
        TimeUtils[Time Utils]
        Logger[Logger]
        RTOS[RTOS/OSAL]
    end
    
    Publisher --> QueueMgr
    QueueMgr --> EventQueue
    SubscriberMgr --> SubscriberLists
    EventProcessor --> QueueMgr
    EventProcessor --> SubscriberMgr
    EventProcessor --> FilterEngine
    
    Components --> Publisher
    Components --> SubscriberMgr
    Publisher --> TimeUtils
    EventProcessor --> Logger
    QueueMgr --> RTOS
```

### 7.2 Event Flow Architecture

```mermaid
graph LR
    subgraph Publishers["Event Publishers"]
        SensorMgr[Sensor Manager]
        STM[State Manager]
        CommMgr[Communication Manager]
        OTAMgr[OTA Manager]
    end
    
    subgraph EventSystem["Event System"]
        EventBus[Event Bus<br/>Publish/Subscribe]
    end
    
    subgraph Subscribers["Event Subscribers"]
        DataPool[Data Pool]
        Persistence[Persistence]
        Diagnostics[Diagnostics]
        HMI[HMI]
        MainHubAPI[Main Hub APIs]
    end
    
    SensorMgr --> EventBus
    STM --> EventBus
    CommMgr --> EventBus
    OTAMgr --> EventBus
    
    EventBus --> DataPool
    EventBus --> Persistence
    EventBus --> Diagnostics
    EventBus --> HMI
    EventBus --> MainHubAPI
```

## 8. Dynamic View

### 8.1 Event Publishing and Delivery Sequence

```mermaid
sequenceDiagram
    participant Publisher as Publishing Component
    participant EventSys as Event System
    participant QueueMgr as Queue Manager
    participant EventProc as Event Processor
    participant Subscriber1 as Subscriber 1
    participant Subscriber2 as Subscriber 2
    
    Publisher->>EventSys: event_publish(type, payload, size)
    EventSys->>QueueMgr: enqueue(event)
    QueueMgr->>QueueMgr: add_to_ring_buffer()
    EventSys-->>Publisher: true (success)
    
    Note over EventProc: Event Processing Task
    EventProc->>QueueMgr: dequeue_next_event()
    QueueMgr-->>EventProc: event
    EventProc->>EventProc: get_subscribers(event.type)
    
    par Parallel Delivery
        EventProc->>Subscriber1: handler(type, payload, size, timestamp)
        Subscriber1-->>EventProc: (callback complete)
    and
        EventProc->>Subscriber2: handler(type, payload, size, timestamp)
        Subscriber2-->>EventProc: (callback complete)
    end
    
    EventProc->>EventProc: update_statistics()
```

### 8.2 Subscription Management Sequence

```mermaid
sequenceDiagram
    participant Component as Component
    participant EventSys as Event System
    participant SubMgr as Subscriber Manager
    participant SubList as Subscriber List
    
    Component->>EventSys: event_subscribe(type, handler, priority)
    EventSys->>SubMgr: add_subscriber(type, handler, priority)
    SubMgr->>SubList: insert_by_priority(handler, priority)
    SubList-->>SubMgr: success
    SubMgr-->>EventSys: success
    EventSys-->>Component: true
    
    Note over Component,SubList: Later: Unsubscribe
    Component->>EventSys: event_unsubscribe(type, handler)
    EventSys->>SubMgr: remove_subscriber(type, handler)
    SubMgr->>SubList: find_and_remove(handler)
    SubList-->>SubMgr: success
    SubMgr-->>EventSys: success
    EventSys-->>Component: true
```

### 8.3 Queue Overflow Handling

```mermaid
sequenceDiagram
    participant Publisher as Publisher
    participant EventSys as Event System
    participant QueueMgr as Queue Manager
    participant Logger as Logger
    
    Publisher->>EventSys: event_publish(type, payload, size)
    EventSys->>QueueMgr: enqueue(event)
    QueueMgr->>QueueMgr: check_queue_full()
    
    alt Queue Full
        QueueMgr->>QueueMgr: drop_oldest_event()
        QueueMgr->>Logger: log_warning("Event queue full, dropping oldest")
        QueueMgr->>QueueMgr: add_new_event()
        QueueMgr-->>EventSys: true (with warning)
    else Queue Available
        QueueMgr->>QueueMgr: add_new_event()
        QueueMgr-->>EventSys: true
    end
    
    EventSys-->>Publisher: result
```

## 9. Interface Definitions

### 9.1 Data Types

```c
// Event Types
typedef enum {
    EVENT_SENSOR_DATA_UPDATE = 0,
    EVENT_DIAGNOSTIC_EVENT,
    EVENT_STATE_CHANGED,
    EVENT_OTA_REQUEST,
    EVENT_OTA_STATUS,
    EVENT_MC_UPDATE_REQUEST,
    EVENT_COMMUNICATION_LINK_STATUS,
    EVENT_STORAGE_STATUS,
    EVENT_SYSTEM_HEALTH_UPDATE,
    EVENT_TEARDOWN_INITIATED,
    EVENT_TEARDOWN_COMPLETE,
    EVENT_SENSOR_FAULT_DETECTED,
    EVENT_SENSOR_STATE_CHANGED,
    EVENT_TYPE_ALL = 0xFF,
    EVENT_TYPE_COUNT
} event_type_t;

// Event Structure
typedef struct {
    event_type_t type;
    uint64_t timestamp;
    size_t payload_size;
    uint8_t payload[];  // Variable-length payload
} event_t;

// Event Handler Callback
typedef void (*event_handler_t)(event_type_t type, const void* payload, size_t payload_size, uint64_t timestamp);

// Event Filter Callback
typedef bool (*event_filter_t)(event_type_t type, const void* payload, size_t payload_size);

// Subscriber Information
typedef struct {
    event_handler_t handler;
    event_filter_t filter;
    uint8_t priority;
    uint32_t call_count;
    uint32_t last_call_time;
} subscriber_info_t;

// Queue Statistics
typedef struct {
    size_t total_events_published;
    size_t total_events_processed;
    size_t total_events_dropped;
    size_t current_queue_size;
    size_t max_queue_size;
    size_t queue_overflows;
    uint32_t avg_processing_time_us;
    uint32_t max_processing_time_us;
    uint32_t total_subscribers;
} event_queue_stats_t;

// Event Priorities
typedef enum {
    EVENT_PRIORITY_LOW = 0,
    EVENT_PRIORITY_NORMAL = 50,
    EVENT_PRIORITY_HIGH = 100,
    EVENT_PRIORITY_CRITICAL = 200
} event_priority_t;
```

### 9.2 Configuration Constants

```c
// Queue Configuration
#define EVENT_QUEUE_SIZE            100     // Maximum events in queue
#define EVENT_MAX_PAYLOAD_SIZE      256     // Maximum payload size in bytes
#define EVENT_MAX_SUBSCRIBERS       10      // Maximum subscribers per event type
#define EVENT_PROCESSING_BATCH_SIZE 5       // Events processed per batch

// Timing Configuration
#define EVENT_PROCESSING_TIMEOUT_MS 10      // Maximum time for event processing
#define EVENT_HANDLER_TIMEOUT_MS    5       // Maximum time for single handler

// Memory Configuration
#define EVENT_BUFFER_POOL_SIZE      (EVENT_QUEUE_SIZE * (sizeof(event_t) + EVENT_MAX_PAYLOAD_SIZE))
```

### 9.3 Error Codes

```c
typedef enum {
    EVENT_SUCCESS = 0,
    EVENT_ERR_INVALID_PARAMETER,
    EVENT_ERR_QUEUE_FULL,
    EVENT_ERR_PAYLOAD_TOO_LARGE,
    EVENT_ERR_SUBSCRIBER_FULL,
    EVENT_ERR_SUBSCRIBER_NOT_FOUND,
    EVENT_ERR_MEMORY_ALLOCATION,
    EVENT_ERR_SYSTEM_NOT_INITIALIZED,
    EVENT_ERR_PROCESSING_TIMEOUT
} event_error_t;
```

## 10. Assumptions and Constraints

### 10.1 Assumptions

- **Event Handlers are Fast:** Event handlers complete within 5ms
- **Memory Availability:** Sufficient memory for event queue and subscriber lists
- **RTOS Availability:** RTOS primitives (mutex, queues) are available
- **Component Cooperation:** Components properly unsubscribe during shutdown

### 10.2 Constraints

- **Non-Blocking Publishing:** Event publishing must never block
- **Memory Limits:** Total memory usage limited to 16KB
- **Queue Size:** Maximum 100 events in queue at any time
- **Payload Size:** Maximum 256 bytes per event payload
- **Subscriber Limit:** Maximum 10 subscribers per event type

### 10.3 Design Constraints

- **No Dynamic Memory:** Use pre-allocated memory pools
- **Thread Safety:** All operations must be thread-safe
- **ISR Safety:** Publishing from ISR context must be supported
- **State Independence:** Event System operates in all system states

## 11. Traceability

### 11.1 Software Requirements

- **SWR-DESIGN-006:** Event System for cross-component communication
- **SWR-DAQ-014:** Publish sensor data updates via Event System
- **SWR-SYS-004:** Notify components of state transitions via Event System

### 11.2 Features

- **F-SYS-01:** System State Management (state change notifications)
- **F-DAQ-01:** Multi-Sensor Data Acquisition (sensor data events)
- **F-DIAG-01:** Diagnostic Code Management (diagnostic events)

### 11.3 Cross-Feature Constraints

- **CFC-TIME-01:** Non-blocking operation
- **CFC-ARCH-02:** State-aware execution (operates in all states)

### 11.4 Architecture Requirements

- **Event-Driven Architecture:** Primary mechanism for component decoupling
- **Asynchronous Communication:** Enables non-blocking inter-component communication

---

**Document Status:** Final for Implementation  
**Dependencies:** Time Utils, Logger, OSAL  
**Next Review:** After component implementation and performance testing