Baji_Rtc_Toy_Key/esp-brookesia-master/service/brookesia_service_manager/README.md

ESP-Brookesia Service Manager

• 中文版本

Overview

brookesia_service_manager is a service management framework for the ESP-Brookesia ecosystem, providing:

• Unified Service Lifecycle: Centralized management of service initialization, startup, stop, and deinitialization through a plugin mechanism.
• Dual Communication Modes:
  • Local Calls: Direct function calls within the device through ServiceBase, featuring thread-safe, non-blocking, and high-performance characteristics.
  • Remote RPC: TCP-based client-server communication for cross-device or cross-language scenarios.
• Event Publish/Subscribe: Supports local and remote event subscription/notification mechanisms.
• RAII-style Binding: Automatic management of service running state (start/stop) on-demand through ServiceBinding.
• Lightweight Dependencies: Mainly depends on esp-idf, brookesia_lib_utils, and esp-boost.
• Decoupling:
  • Project code is completely decoupled from service implementations; to use a service, project code only needs to call the Service Manager API, while service implementations focus solely on business logic. The two are connected via a plugin mechanism.
  • To use a target service, the project only needs to add a dependency on the desired service component, without needing to modify its own code.

Table of Contents

• ESP-Brookesia Service Manager
  • Overview
  • Table of Contents
  • Communication Architecture
    • 1. Local Mode
    • 2. Remote RPC (Remote Procedure Call) Mode
    • Local Calls vs Remote RPC
  • How to Use
    • Development Environment Requirements
    • Add to Project
  • Usage Examples

Communication Architecture

The brookesia_service_manager framework supports two communication modes:

1. Local Mode

flowchart TB
    App["App/User Code"]
    SM["ServiceManager"]
    Binding["ServiceBinding"]
    Base["ServiceBase"]
    Registry["FunctionRegistry & EventRegistry"]

    App -->|"bind()"| SM
    SM -->|"returns"| Binding
    Binding -->|"get_service()"| Base
    Base -->|"call_function_sync()<br/>call_function_async()<br/>subscribe_event()"| Registry

    style App fill:#e1f5ff
    style SM fill:#fff4e1
    style Binding fill:#f0e1ff
    style Base fill:#e1ffe1
    style Registry fill:#ffe1e1

ASCII Diagram:

[App/User Code]
       |
       | ServiceManager.bind()
       v
[ServiceBinding] ----> [ServiceBase]
                            |
                            |-- call_function_sync() / call_function_async()
                            |-- subscribe_event()
                            v
          [FunctionRegistry & EventRegistry]

2. Remote RPC (Remote Procedure Call) Mode

flowchart LR
    subgraph Client_Side["Client Device"]
        App["App/User Code"]
        Client["RPC Client"]
        Dispatcher["EventDispatcher"]
    end

    subgraph Network["Network Layer"]
        DataLink["DataLink<br/>(TCP Socket)"]
    end

    subgraph Server_Side["Server Device"]
        Server["RPC Server"]
        Base["ServiceBase"]
        Registry["EventRegistry &<br/>FunctionRegistry"]
    end

    App --->|"call_function / <br/>subscribe_event"| Client
    Client --->|"Request"| DataLink
    DataLink --->|"Response"| Client
    DataLink <-->|"Forward"| Server
    Server <-->|"invoke"| Base
    Base <-->|"access"| Registry
    App <---|"event callback"| Dispatcher
    DataLink -.->|"Notify"| Dispatcher

    style App fill:#e1f5ff
    style Client fill:#f0e1ff
    style Dispatcher fill:#ffe1f0
    style DataLink fill:#fff4e1
    style Server fill:#f0e1ff
    style Base fill:#e1ffe1
    style Registry fill:#ffe1e1

ASCII Diagram:

                                <--------- Response & Notify ----------
[App/User Code] <-> RPC Client |<--- DataLink (TCP Socket + JSON) ---->| RPC Server <-> [ServiceBase]
       ^                |       --------------- Request -------------->                       |
       |                |                                                                     |
       |                v                                                                     v
       +-------- EventDispatcher                                                EventRegistry & FunctionRegistry

Local Calls vs Remote RPC

Comparison Item	Local Calls (ServiceBase)	Remote RPC (rpc::Client)
Deployment	✅ Same device	✅ Cross-device communication
Communication	Direct function calls	TCP Socket + JSON
Latency	⚡ Millisecond level (very low)	⚠️ Millisecond to second level (depends on network)
Performance	✅ High performance, minimal serialization overhead	⚠️ Requires extensive serialization/deserialization
Frequency	✅ High-frequency calls	⚠️ Medium to low-frequency calls
Thread Safety	✅ Built-in async scheduling, thread-safe protection	✅ Network isolation
Language Support	C++ only	✅ Language-independent (Socket + JSON protocol)
Network Dependency	❌ No network required	✅ Same local area network
Typical Scenarios	In-device service collaboration	Cross-device or cross-language service calls

How to Use

Development Environment Requirements

Before using this library, ensure you have installed the following SDK development environment:

• ESP-IDF: >=5.5,<6

Note

For SDK installation instructions, please refer to ESP-IDF Programming Guide - Installation

Add to Project

brookesia_service_manager has been uploaded to the Espressif Component Registry. You can add it to your project in the following ways:

1. Using Command Line

   Run the following command in your project directory:

   idf.py add-dependency "espressif/brookesia_service_manager"
   

2. Modify Configuration File

   Create or modify the idf_component.yml file in your project directory:

   dependencies:
     espressif/brookesia_service_manager: "*"
   

For detailed instructions, please refer to Espressif Documentation - IDF Component Manager.

Usage Examples

Please refer to Usage Examples for detailed usage examples.