Giters

SecretariatV / areg-sdk

AREG is an interface-centric and cross-platform ORPC (Object RPC) framework that allows devices and software nodes to interact as distributed servers and clients.

Home Page:https://www.aregtech.com

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

AREG SDK Home

AREG SDK

Latest release GitHub commits Stars Fork Watchers

Project Status

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

Introduction

AREG (Automated Real-time Event Grid) is a communication engine that enables data transmission in IoT fog- and mist-network. It is lightweight, automated, featured, and works on different platforms. AREG uses an interface-centric approach to create a grid of services that allows multiple devices and software nodes to operate like distributed servers and clients. By automating real-time data transmission, and using both Client-Server and Publish-Subscribe models, AREG ensures reliable and efficient communication between connected software nodes.

Table of contents

Motivation

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

IoT-to-Cloud (Nebula) network

As data is generated and collected at the edge of the network (mist network), it is logical to redefine the role of connected Things and enable network-accessible services (Public Services) on them, thereby extending the Cloud to the extreme edge. This approach serves as a strong foundation for implementing robust solutions such as:

  • Increase data privacy, which is an important factor for sensitive data.
  • 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

ORPC, or Object Remote Procedure Call, is a remote procedure call concept that targets an interface on an object. It enables the construction of a service mesh (or service grid), where applications offer reusable services, and programmable client objects request method execution of programmable server objects without needing to know their location in the network.

Service oriented and interface-centric

The ORPC concept is interface-centric, similar to object-oriented programming, and supports transparent handling of multiple instances of the same object. There are no protocol restrictions, although the bi-directional communication is necessary to send messages to all connected nodes. The programmable server objects are called Service Providers, and the programmable clients are called Service Consumers. This approach enables AREG to combine the features of action-centric (Client-Server / Request-Reply) and data-centric (Publish-Subscribe / PubSub) models.

More than embedded

The interface-centric nature of AREG engine provides a distributed solution for embedded application. AREG is designed to provide a homogeneous solution for multithreading, multiprocessing, and internet communications through categorized services (Local, Public, and Internet). These services are software components with predefined interfaces, which methods are invoked remotely.

AREG SDK distributed services

💡 Currently AREG engine supports Local (multithreading) and Public (multiprocessing) service categories.

AREG forms a fault-tolerant system that automatically discovers and automates communications between services, allowing developers to focus on application logic development. The system ensures:

  • The crash of one application does not affect the entire system.
  • The clients automatically receive service availability notifications.
  • The requests, responses, and notifications are invoked in their own thread context.

Composition

At present, the Automated Real-time Event Grid software development kit (AREG SDK) comprises the following primary modules:

  • Multicast router (mcrouter): a console application or OS-managed service that facilitates the message routing.
  • The AREG engine: a framework library that enables communication between software components.
  • Code generator: a tool to generate service Provider and Consumer objects from interface documents.

Furthermore, the AREG SDK includes a variety of examples, which illustrate the robust characteristics and functionality of the AREG communication engine. Additionally, there are various user interface (UI) tools currently in the development stage that aim to simplify and expedite the process of designing services and applications, as well as analyzing and interacting with applications on remote machines.

Clone sources

To obtain the AREG SDK source codes and the dependent modules, run the git-command in your projects folder:

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

Alternatively, to clone only the submodule sources, run the git-command in the AREG SDK root folder:

git submodule update --init --recursive

To update the AREG SDK to the latest submodule sources, use the git-command:

git submodule update --remote --recursive

💡 Please note that after running this git-command, your submodule sources may differ from the sources that AREG SDK uses.

Quick build

The source codes of the AREG SDK are implemented using C++17 and can be compiled on multiple platforms, CPUs, and compilers.

  • Supported compilers: GCC, Clang, Cygwin GCC, and MSVC.
  • Supported platforms: Windows, Linux, and macOS.
  • Supported CPU: x86, x86_64, arm, and aarch64.

To compile the sources, the following tools can be used:

Tool Solution Platforms API Quick actions to compile
cmake CMakeLists.txt Linux, Cygwin, Windows POSIX, Win32 - Build with cmake.
- Build in VSCode.
- Build in MSVS.
make Makefile Linux, Cygwin POSIX - Build with make.
msbuild areg-sdk.sln Windows Win32 - Build with msbuild.
- Open and build in MSVS.

After compilation, the binaries are stored in the <areg-sdk>/product/build/<family>-<compiler>/<platform>-<bitness>-<cpu>-<build type>/bin folder. For example, if the code is compiled with GNU GCC on a 64-bit Linux system with an x86_64 CPU and in release mode, the binaries will be in the ./product/build/gnu-gcc/linux-64-x86_64-release/bin subfolder of areg-sdk.

To obtain comprehensive information regarding builds and options for the AREG SDK, we recommend referring to the Software build page on the AREG SDK Wiki. This document provides a brief outline of the compilation process using default options.

💡 Other POSIX-compliant operating systems and compilers have not yet been tested. List of supported POSIX APIs.

Build with cmake

Click to show / hide Build with cmake.

To build the AREG and examples using CMake, ensure that you have cloned the sources properly as described earlier. Open the Terminal in the areg-sdk directory and follow these steps:

  1. Initialize the cache and build configuration with default options (g++ compiler, release build, build examples and unit tests):
cmake -B ./build
  1. Compile the sources, justify parallel jobs with -j option:
cmake --build ./build -j 8

💡 For instructions on how to customize builds with cmake tool, kindly refer to the Build with CMake Wiki page.

Build with make

Click to show / hide Build with cmake.

To build the AREG and examples using Make, ensure that you have cloned the sources properly as described earlier. Open the Terminal in the areg-sdk directory and compile sources with default options (g++ compiler, release build, build examples and unit tests), justify parallel jobs with -j option:

make -j 8

💡 For instructions on how to customize builds with make tool, kindly refer to the Build with Make Wiki page.

Build with msbuild

Click to show / hide Build with msbuild.

To build the AREG and examples using MSBuild, ensure that you have cloned the sources properly as described earlier. Open the Command Prompt in the areg-sdk directory and compile sources with default options (MSVC compiler, release build, build examples and unit tests):

MSBuild .

💡 For instructions on how to customize builds with make tool, kindly refer to the Build with MSBuild Wiki page.

Build with WSL

Click to show / hide Build with WSL.

The Windows Subsystem for Linux (WSL) allows developers to use Linux applications directly on Windows machines. This means that developers may clone, compile and use AREG engine in a popular Linux distributions. To install and update WSL on your Windows 10 machine, clone and compile AREG SDK sources, and run examples, please follow the step-by-step instructions outlined in the Compile in Windows Subsystem for Linux (WSL) Wiki page.

Build with IDEs

Click to show / hide Build with IDE.

💡 This chapter focuses on building AREG and examples using Microsoft Visual Studio and Visual Studio Code. The other IDEs are currently not in the focus.

To build the AREG and examples using Microsoft Visual Studio or Visual Studio Code, ensure that you have cloned the sources properly as described earlier and follow the instructions.

Build with Microsoft Visual Studio

  1. Open areg-sdk.sln in Microsoft Visual Studio.
  2. Build the solution with MSVC.

Build with Visual Studio Code

  1. Open the areg-sdk folder in Visual Studio Code.
  2. In the Explorer panel, select CMakeLists.txt.
  3. Right-click on the file, select Configure All Projects from the context menu and wait for completion.
  4. Right-click on the file again and select Build All Projects to build the sources with the default options.

Integration

The AREG framework offers developers the flexibility to either build their own project on top of it or integrate the framework into an existing project in order to develop separate software layers or components.

Start a project

Click to show / hide Start a project.

The best practice is to review sample projects provided in this repository. As a guidance to start a project and step-by-step example, refer to the Hello Service! document, which showcases various scenarios for creating Local and Public Service Providers and Service Consumers. In addition, review the file structure guidelines presented in the DEVELOP.mde document.

To begin a project:

  1. Create a Service Interface XML document that describes the service, including data types, attributes, and methods. Then, use the provided code generator tool to generate base sources for the service components. We recommend including these generated sources in a static library to link with each module.
  2. Create projects that provide and/or consume services in AREG, extend the Stub or ClientBase objects and implement the required overrides. For Service Providers, implement all request methods. For Service Consumers, it may be sufficient to implement relevant overrides for Responses and data update Notifications.
  3. Define a model for your application(s), describe the threads and dependencies between service components. Load the model in the main() function. Compile and link projects with the static library of generated codes and the areg library, which serves as the AREG communication engine.

💡 The Service Interface design tool with a GUI is currently under development as an open source project, and will be included to the repository when it is ready.

The AREG engine facilitates transparent communication between Service Providers and Service Consumers, making it flexible and automated. In the case of Public services, the Providers and Consumers can be located on any software node. The AREG SDK introduces the concept of a model, which describes the service Providers and Consumers. The models can be dynamically loaded and unloaded during runtime, allowing for the activation and deactivation of defined services as needed.

Here's a brief example of defining a model that is loaded and unloaded during runtime, enabling multithreading communication between a Service Provider and a Service Consumer within the same application:

BEGIN_MODEL("ServiceModel")
    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")
        
    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("ServiceModel")

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

For multiprocessing communication, the model can be split into two parts. One application loads the model to instantiate the Service Provider, while another application loads the model to instantiate the Service Consumer. Once the Service Provider is instantiated and available, the Service Consumer is automatically notified of the service availability and can initiate communication accordingly.

Configure multicast router

Click to show / hide Configure multicast router.

To configure the Multicast Router, adjust the router.init file by specifying the IP address and port of the mcrouter:

connection.address.tcpip    = 127.0.0.1	# IP address of the mcrouter host
connection.port.tcpip       = 8181      # connection port of the mcrouter

Note that the Multicast Router is necessary only for applications that provide or consume Public services (multiprocessing applications) and can be ignored for application using only Local services (multithreading applications). The Multicast Router can run on any machine with GPOS (General Purpose Operating System). It establishes a network between connected applications and responsible to route messages between programmable service components.

Configure logging

Click to show / hide Configure logging.

Applications based on the AREG framework can be compiled with or without logging. If you choose to compile with logging, you'll need to configure log.init to set scopes, priorities, and file names for logging.

Here's an example configuration for the log file:

log.file        = %home%/logs/%appname%_%time%.log # creates logs in the 'log' subfolder of the user's home directory
scope.mcrouter.*= NOTSET ;                         # disables logs for mcrouter.

scope.my_app.*                   = DEBUG | SCOPE ; # enables all logs of my_app
scope.my_app.ignore_this_scope   = NOTSET ;        # disables logs for a certain scope in my_app
scope.my_app.ignore_this_group_* = NOTSET ;        # disables logs for a certain scope group in my_app

Please refer to the AREG Engine Logging System Wiki page for detailed instructions on compiling applications with enabled or disabled logging, start and stopping logs during runtime, as well as creating and using logging scopes, and configuring in the log.init file.

💡 By default, the router.init and log.init files are located in the config subfolder of binaries.
💡 To enable logging for all applications, use scope.* = DEBUG | SCOPE ;.
💡 At present, logging is only possible in the file.

Roadmap

The goal of the AREG SDK is to provide a lightweight, self-sufficient development and testing system to help developers create complex applications for Desktop, Embedded, and IoT edge devices in a shorter amount of time (30-50% faster).

Here are the planned features of the framework:

  • Multi-channel and multi-protocol communication.
  • Logging service to collect logs in the network.
  • Internet (web) category services.

And here are the planned tools:

  • Service interface designer.
  • Interactive log viewer.
  • Service testing and data simulation tool.

The development of the AREG SDK tools is currently underway in a separate repository called AREG SDK Tools, which is a part of the larger AREG SDK project.

Use cases and benefits

The AREG SDK is a dynamic and flexible tool that offers a vast array of use cases for multithreading and multiprocessing application development. The communication engine has been successfully used in a variety of scenarios, from practical examples to real-world applications. Its proven capabilities and potential for success make it a popular choice for developers seeking to create intelligent devices for embedded and IoT applications.

To explore the various use cases of the AREG communication engine, including distributed solutions for embedded applications, driverless devices, real-time solutions, digital twins, and simulation and tests, refer to the AREG Engine Use Cases and Benefits document.

Examples

There are various examples to demonstrate features of the AREG communication engine. The examples are part of SDK and are listed in the examples/README.md document.

License

AREG SDK is under free open source Apache License Version 2.0. However, AREG SDK can be commercially licensed, which includes the commercial support, full rights to create and distribute software without open source license obligations. For commercial license, support or additional information, please visit Aregtech website or contact info[at]aregtech[dot]com.

Call to action

Join our project and provide assistance by:

  • Checking out the list of open issues where we need help.
  • If you need new features, please open a new issue or start a discussion.
  • hen creating a pull request, kindly consider the time it takes for reviewing and testing, and maintain proper coding style.
  • If you require invoiced commercial support or training, or if you wish to support AREG SDK commercially, kindly contact us at info[at]aregtech[dot]com.

Please Star AREG SDK repository to encourage contributors and helps to grow our community. Contact us for the feedback or new ideas.

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 for @aregtech/areg-sdk

Follow us at
Follow us on twitter 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 Twitter  Share on Facebook  Share on Telegram  Share on Whatsapp 

About

AREG is an interface-centric and cross-platform ORPC (Object RPC) framework that allows devices and software nodes to interact as distributed servers and clients.

https://www.aregtech.com

License:Apache License 2.0

Languages

Language:C++ 96.9%Language:C 1.3%Language:CMake 0.9%Language:Makefile 0.7%Language:Batchfile 0.1%Language:Shell 0.0%