Skip to content

Latest commit

 

History

History
452 lines (312 loc) · 29.5 KB

README.md

File metadata and controls

452 lines (312 loc) · 29.5 KB
Raw

AREG SDK Home

AREG SDK

Discover AREG - an advanced framework for real-time communication in mist- and fog- network environments.

Latest release GitHub commits Stars Fork Watchers Wiki Pages

Project Status

CMake build MS Build CodeQL
C++ solution Operating systems CPU Architect

Introduction

AREG Framework (Automated Real-time Event Grid) is an asynchronous, interface-driven communication engine that enables connected software nodes to form a network of distributed services. By facilitating seamless remote object interactions, AREG allows nodes to communicate without knowledge of their network locations, as if they coexist within the same process and thread. Lightweight and designed for IoT fog- and mist-network, it empowers devices to deliver real-time public services, enabling efficient remote access and collaboration.

Table of contents

Important

For full technical guidance of building and using AREG SDK, see the following documents.

Motivation

Traditionally, devices act as connected clients to stream data to the cloud or fog servers for further processing.

Diagram showing IoT-to-Cloud (Nebula) network connections

As data is generated and collected at the edge of the network (mist network), there is a growing need to redefine the role of connected Things and enable network-accessible Public Services on the edge device, thereby extending the Cloud capabilities to the extreme edge. This approach provides a robust foundation for solutions like:

  • Enhancing data privacy, which is crucial for sensitive information.
  • Decrease data streaming, which is a fundamental condition to optimize network communication.
  • Autonomous, intelligent and self-aware devices with services directly in the environment of data origin.

Interface-centricity

At the core of AREG is ORPC (Object Remote Procedure Call), which targets interfaces on objects. This allows AREG to establish a service mesh or service grid where applications expose reusable services. Clients, without knowledge of the server's network location, can request services seamlessly via method invocation.

Diagram showing multiprocess communication

This interface-driven Object RPC model mirrors object-oriented programming principles and is flexible in managing multiple object instances. It imposes no protocol limitations and supports bi-directional communication to ensure seamless messaging between connected software nodes. In this model:

  • Service Providers (micro-server objects) offer reusable, accessible services.
  • Service Consumers (micro-client objects) invoke services without needing to know the network details.

AREG's design integrates Client-Server (Request-Reply) and Publish-Subscribe (PubSub) models, enabling it to support both action- and data-centric communication.

More than Embedded

The architecture of AREG is ideal for embedded applications, but its capabilities extend far beyond. AREG offers distributed and scalable solutions for multithreading, multiprocessing, and internet communications, making it a versatile choice for a wide range of applications. Services in AREG are categorized into three types: Local, Public, and Internet, enabling flexible and efficient remote communication across diverse environments.

Diagram showing Services and AREG Framework message handling

Note

AREG currently supports Local (multithreading) and Public (multiprocessing) services.

The fault-tolerant design of AREG offers key advantages, such as:

  • Resilience: Failure in one application does not affect the overall system.
  • Automatic Discovery: Services are automatically discovered by clients without manual configuration.
  • Thread-Safe Execution: All service methods are executed within their respective thread contexts, ensuring thread safety and independence.

Composition of AREG SDK

The AREG SDK consists of several modules to streamline distributed, real-time applications development:

Note

The UI tool Lusan is currently under the development. It is supposed to provide multiple features like Service Interface design, log viewing, and runtime testing. We call to join this open source project to develop the tool.

Getting Started: Clone and Build the AREG SDK

General Requirements

Ensure your system includes the following:

  • Git for repository cloning.
  • Compatible Compilers: GNU, LLVM, or MSVC (Windows only) supporting C++17 or newer.
  • CMake (version 3.20+).
  • Java (version 17+ for code generation tools).
  • Optionally, you may install following packages:
    • ncurses library to support optional objects with extended features in Linux or Cygwin;
    • CMake, Clang and MFC packages of Microsoft Visual Studio;
    • SQLite and GTest packages.

Cloning Sources

To obtain the AREG SDK source codes, use the following command:

git clone https://github.com/aregtech/areg-sdk.git

Build Instructions

The AREG SDK is written in C++17, supports multiple platforms, processors and compilers:

Compiler Platforms Tools API CPU Architecture
GNU Linux, macOS CMake POSIX x86, x86_64, ARM, AARCH64
Clang Linux, Windows CMake, MSVS POSIX, Win32 x86, x86_64, ARM, AARCH64
MSVC Windows CMake, MSVS Win32 x86, x86_64
Cygwin GNU Windows CMake POSIX x86, x86_64

Note

Other POSIX-compliant operating systems and compilers have not been tested yet.

Build with CMake

To compile the AREG SDK using CMake, follow these steps:

cmake -B ./build
cmake --build ./build -j 20

Tip

By default, AREG SDK sources are built with Examples and Unit Tests. To exclude AREG Unit Tests from the build process, set the AREG_BUILD_TESTS CMake option to OFF. Similarly, to exclude AREG Examples, set the AREG_BUILD_EXAMPLES CMake option to OFF.

Below is an example of configuring and building the AREG SDK sources without Unit Tests and Examples:

cmake -B ./build -DAREG_BUILD_TESTS=OFF -DAREG_BUILD_EXAMPLES=OFF
cmake --build ./build

For further details on customizing builds or cross-compiling with CMake see Building AREG SDK with CMake page.

Build with Microsoft Visual Studio

Open areg-sdk.sln file in Microsoft Visual Studio and build the solution, or navigate to the root directory of the project and run build with MSBuild:

MSBuild ./areg-sdk.sln

For further details on customizing builds with Visual Studio, visit the Building the AREG SDK with Microsoft Visual Studio and MSBuild page.

Additional Build Options

Integration and Development

For a practical example of building real-time, distributed systems using AREG SDK, check out the AREG SDK Demo project, which includes implementations of multitasking applications for embedded, IoT mist- and fog-systems.

AREG SDK Integration Methods

There are three ways to integrate the AREG SDK into your project:

1. Integrate by Fetching sources

Add the following script to your CMakeLists.txt to integrate AREG SDK:

find_package(areg CONFIG)
if (NOT areg_FOUND)
    include(FetchContent)
    FetchContent_Declare(
        areg-sdk
        GIT_REPOSITORY https://github.com/aregtech/areg-sdk.git
        GIT_TAG "master"
    )
    FetchContent_MakeAvailable(areg-sdk)
    set(AREG_SDK_ROOT "${areg-sdk_SOURCE_DIR}")
    include_directories("${AREG_SDK_ROOT}/framework")
endif()

include("${AREG_SDK_ROOT}/areg.cmake")

This either finds or fetches the AREG SDK components from master branch. See the Building AREG SDK with CMake page for more details.

2. Integrate as a project submodule

  1. Add areg-sdk as a Git submodule in your project.
  2. Include areg-sdk project in your build:
    • Microsoft Visual Studio: include the *.vcxproj files from <areg-sdk>/framework in your solution.
    • CMake: include the <areg-sdk-root>/CMakeLists.txt in your CMake script.
  3. Link your projects with the areg library and set project dependencies.

For full details, see the Building the AREG SDK with Microsoft Visual Studio and MSBuild.

3. Integrate the areg Package (vcpkg)

Important

Starting with AREG SDK 2.0, you can integrate it using the vcpkg package manager.

Before starting, visit the official vcpkg repository to clone and install the vcpkg package manager tool in your PC.

  1. Install and integrate the areg package: Example of the AREG SDK components, headers and its dependencies installation under Linux:

    ./vcpkg install areg:linux-64
./vcpkg integrate install

  2. Integrate with CMake: Add the following script to your CMakeLists.txt (replace <example> with real target):

    find_package(areg CONFIG REQUIRED)
target_link_libraries(<example> PRIVATE areg::areg)

    Use vcpkg toolchain file (<vcpkg-root> is the root path of vcpkg) to configure and build the project:

    cmake -B ./build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake
cmake --build ./build -j 20

  3. Integrate with Microsoft Visual Studio: In Microsoft Visual Studio, there is no need to add AREG SDK projects in the solution file. Develop projects and make sure to link areg library with binaries either in Project Properties or by adding this line of code:

    #pragma comment(lib, "areg")

For details of installing and using areg package, see the appropriate integrate areg package document.

Service Creation and Development

Follow the “Hello Service!” tutorial for step-by-step instructions. Generated service interface files integrate with CMake or Visual Studio projects. Service Providers extend xxxStub, and Service Consumers extend xxxClientBase.

Example: Application Model Setup

When developing Service Provider and Service Consumer components, developers can easily determine whether to run components in the same process (multithreading) or in separate processes (multiprocessing) for optimal performance in real-time applications by defining the Application Model. Below is an example of setting up a model where the Service Provider and Service Consumer components run in the same process, but on different threads.

BEGIN_MODEL("ApplicationModel")
    // Provider Thread
    BEGIN_REGISTER_THREAD("ProviderThread", NECommon::WATCHDOG_IGNORE)
        BEGIN_REGISTER_COMPONENT("ServiceProvider", ServiceComponent)
            REGISTER_IMPLEMENT_SERVICE(NEHelloService::ServiceName, NEHelloService::InterfaceVersion)
        END_REGISTER_COMPONENT("ServiceProvider")
    END_REGISTER_THREAD("ProviderThread")
        
    // Consumer Thread
    BEGIN_REGISTER_THREAD("ConsumerThread", NECommon::WATCHDOG_IGNORE)
        BEGIN_REGISTER_COMPONENT("ServiceConsumer", ClientComponent)
            REGISTER_DEPENDENCY("ServiceProvider")
        END_REGISTER_COMPONENT("ServiceConsumer")
    END_REGISTER_THREAD("ConsumerThread")
END_MODEL("ApplicationModel")

int main(void)
{
    Application::initApplication();
    Application::loadModel("ApplicationModel");
    Application::waitAppQuit();
    Application::unloadModel("ApplicationModel");
    Application::releaseApplication();
    return 0;
}

In this example:

  • ServiceProvider runs on ProviderThread, and ServiceConsumer runs on ConsumerThread.
  • REGISTER_DEPENDENCY("ServiceProvider") means ServiceConsumer component consumes the services provided by ServiceProvider.

You can also set up multiprocess applications using same components and changing model. As a practical example, follow projects in the 00_helloservice directory.

Tip

Learn how AREG SDK simplifies the creation of Service Providers and Consumers, supporting both multithreading and multiprocessing for real-time, distributed applications. Visit examples to see the list of demonstrated applications and features of the AREG communication engine.

Multicast Router and Log Collector

mcrouter and logcollector are essential services within the AREG SDK ecosystem, enabling seamless communication and efficient logging. Configuration templates for both are included in the areg.init file, which is placed in the config subdirectory of the build binaries. These applications can function as standalone console tools or be deployed as Operating System managed services, providing deployment flexibility.

For detailed instructions on building and using these services, see the Multicast Router Service and Log Collector Service documentation. Explore how they enhance communication and logging in real-time and edge-computing environments.

Examples

The AREG SDK offers hands-on examples demonstrating Multithreading and Multiprocessing applications, Client-Server and Publish-Subscribe models, Object Remote Procedure Call (Object RPC) and Inter-Process Communication (IPC), featured Finite-State Machines (FSM) creation, and more. Each project highlights key features that facilitate efficient development of distributed services.

Some Featured Examples:

  1. 00_helloservice: Master service creation across single-threaded, multi-threaded, and multi-process environments, showcasing AREG's intuitive, interface-driven approach.

  2. 04_logging: Configure and manage logging to track application behavior, aiding debugging, performance analysis, and log management.

  3. 16_pubfsm: Build and control a Finite-State Machine (FSM) with AREG's Timers and Events for smooth state transitions.

  4. 19_pubwatchdog: Implement a watchdog to monitor thread activity, restart unresponsive threads, and notify components as needed.

  5. 24_pubsubmulti: Explore the PubSub model, which reduces data traffic by delivering only relevant updates.

For the full list of examples and additional documentation, visit AREG SDK Examples.

Accelerate your multithreading, multiprocessing, embedded, IoT edge, and event-driven development with these examples. For technical inquiries, please contact us.

Pipeline and Roadmap

The AREG SDK is continuously evolving to help developers create complex applications more efficiently on Desktop, Embedded, and IoT edge devices. It aims to reduce development time by 30-50% while ensuring automation, reliability and flexibility.

Upcoming Features:

  • Multi-channel & multi-protocol communication: Enhanced support for various communication methods, improving interoperability.
  • Internet category services: Expansion into web-based services, enabling more modern, internet-driven applications.

Tools in Development:

  • Service Interface Designer: A visual tool to simplify service interface creation.
  • Interactive Log Viewer: A tool for easy log visualization and performance analysis.
  • Service Testing & Simulation Tool: Helps simulate services and data, streamlining testing and development.

The tools are actively being developed in the AREG SDK Tools repository.

Use Cases and Benefits

The AREG SDK enables efficient multithreading and multiprocessing communication, offering full support for edge computing and fog computing use cases that demand efficient communication between devices and services in real-time. It is ideal for developing:

  • Distributed solutions for embedded systems.
  • Real-time applications for IoT devices.
  • Simulation and test environments.

Explore real-world use cases and examples to learn more about its applications.

License

The AREG SDK is available under the Apache License Version 2.0, a permissive free open-source license. For developers or businesses that need commercial licensing, this option is available and includes:

  • Commercial support.
  • Full rights to create and distribute software without open-source license obligations.

For more information on commercial licensing, commercial support, trainings, or partnership inquiries, visit the Aregtech website or contact us at info[at]aregtech[dot]com.

Call to action

We encourage the developer community to get involved and contribute to the growth of the AREG SDK. Join AREG SDK community and collaborate with AREG developers. Here's how you can help:

  • Check out our list of open issues where assistance is needed.
  • If you have suggestions or need new features, open a new issue or start a discussion.
  • For pull requests, ensure that the code adheres to our coding style and allow time for review and testing.

Lastly, help us grow the AREG SDK community by giving a star on GitHub! Whether you're working on embedded applications, multiprocessing and multithreading applications, real-time data transfer, IoT applications, or microservices architecture, your support helps us continue to improve this cutting-edge communication framework.

Thank you all!

Special thanks to all contributors and supporters that starred this repository.

Our amazing contributors:

Contributors for @aregtech/areg-sdk

Our supportive stargazers:

Stargazers of @aregtech/areg-sdk repo

Do you like this project? Join us or give a ⭐.
Do you have an idea or found a bug? Please open an issue or start a discussion.

Follow us at
X (formerly Twitter) Follow Follow us on LinkedIn Join the chat at https://gitter.im/areg-sdk/community

Share the project link with your network on social media.

Share on Reddit  Share on LinkedIn  Shared on X  Share on Facebook  Share on Telegram  Share on Whatsapp