RDK Resources
[*RDK Preferred*]
Code Management Facility
RDK Forums
[RDK Conferences]
RDK Support
Archives
Papers & Presentations Archive
Page History
| Table of Contents |
|---|
Introduction
RDK Bus (RBus) is a lightweight, fast and efficient bus messaging system. It allows inter-process communication (IPC) and remote procedure call (RPC) between multiple processes running on a hardware device. It supports the creation and use of a data model, which is a hierarchical tree of named objects with properties, events, and methods.
The RDK Bus aims to create a unified IPC bus compatible with all RDK profiles, structured into three layers. At the base is rtMessage, which delivers essential messaging functions over Unix domain or TCP sockets. Above this layer is RBus-core, which provides intermediate RPC and eventing capabilities. At the top is the RBus APIs, offering a streamlined set of unified Bus APIs designed for consistent use across all RDK profiles.
draw.io Diagram border true diagramDisplayName RBUS API lbox true revision 1 diagramName Untitled Diagram-1726808673638 aspect lXQID9y_WnDtvRTX6Ov8 1 simpleViewer false width 600 aspectHash 6a3df934fe480fb56ff3f9d2414742c0afcef593 links auto tbstyle top diagramWidth 1091 height 651
All new components in RDK-B would make use of this RBus APIs. For backward compatible reasons, the RBus APIs would still be made interoperable with the older CCSP Common Lib Interface.
Architecture and Design
The RBus would provide 4 types of functionalities to the components.
- Data Model Registration APIs
- Component / Data Model discovery APIs, Eventing APIs
- Data Model (get / set) APIs
- Methods support
The below diagram illustrates how components would be interacting with each other. It shall be noted that (for backward compatibility reasons) both common lib and the RBus lib coexists in the system.
draw.io Diagram border true diagramName Untitled Diagram-1726812972277 simpleViewer false links auto tbstyle top diagramDisplayName RBus Architecture lbox true diagramWidth 361 height 521 revision 1
Providers and Consumers APIs
- APIs for provider components to perform
- Register properties and implement their get and set operations.
- Register handlers for add / remove operations for table rows.
- Register and publish events.
- Register and implement methods which can be called remotely.
- APIs for consumer components to perform
- Get and set property values. Discovery APIs for components and elements.
- Get, set properties. Add, remove rows in tables.
- Subscribe and listen to events.
- Invoke remote methods.
DMCLI to enable/disable RBus
- enable RBus Mode on the device:
- dmcli eRT setv Device.DeviceInfo.X_RDKCENTRAL-COM_RFC.Feature.RBus.Enable bool true
- disable RBus Mode on the device:
- dmcli eRT setv Device.DeviceInfo.X_RDKCENTRAL-COM_RFC.Feature.RBus.Enable bool false
Key Operations in RBus
The primary operations performed within the RBus are:
Property Management
- This involves managing properties or parameters within RBus.
- It includes detecting changes in property values, sending notifications about these changes, and responding to updates.
- This operation is crucial for keeping the system’s data current and responsive to changes.
- Examples: RBusValueChangeProvider, RBusValueChangeConsumer
Method Execution
- This operation enables remote procedure calls within RBus.
- It involves offering methods that can be invoked remotely by other components.
- This facilitates interaction and execution of functions across different parts of the system, enabling modular and distributed application design.
- Examples: RBusMethodProvider, RBusMethodConsumer
Event Management
- Event management encompasses generating, subscribing to, and processing events.
- It involves sending out events when certain conditions are met and listening for these events to perform specific actions.
- This operation is crucial for implementing reactive and event-driven architectures.
- Examples: RBusEventProvider, RBusEventConsumer, RBusGeneralEventProvider, RBusGeneralEventConsumer
Event Registration
- When subscriptions reach the provider, the provider will write these to a provider specific cache file on disk.
- Upon restart, the provider loads this cache file into memory and reapplies the subscriptions for registered events.
The RBus_open function calls deserializeFromDisk to find and load the cache file, named after the component (assumed to be unique and consistent across restarts). The file is stored in the device's temporary directory, which is cleared on boot.
- On the first run after boot, the cache file does not exist, so the provider startup without caching as if were not enabled. However, if the provider restarts (due to a crash or service restart), it will read and apply the cached file subscriptions.
- For each subscription, all info needed to recreate the subscription should be stored, including the subscriber address and any filter for that subscriber.
| draw.io Diagram | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Event Subscription
- Under event subscription, we do not notify the broker. The broker is unaware of subscriptions.
- To support startup ordering, a consumer will do subscribe retries. If the provider hasn't come up and registered the event yet, the consumer will get an error on subscribe.
- Using retry logic, they will successfully register once the provider comes up.
- If the provider doesn't come up, because it isn't supported on the device, or a particular event is never registered because it is not supported on the device, then the consumer will never get a successful subscribe and can avoid enabling code to support the event or feature requiring the event.
| draw.io Diagram | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Table Management
- This operation involves managing table data structures within RBus.
- It includes operations for accessing, manipulating, and maintaining table data, which is crucial for handling complex data sets and ensuring efficient data organization and retrieval.
- Examples: RBusTableProvider, RBusTableConsumer
Data Model Operations
- This includes the fundamental operations of RBus, such as opening connections, registering parameters, and retrieving values.
- These operations form the core functionalities of RBus, enabling basic communication and data exchange between different components.
- Examples: RBusSampleProvider, RBusSampleConsumer
Subscription Management
- This involves managing subscriptions to various events and properties.
- It includes subscribing to notifications, handling subscription callbacks, and managing the lifecycle of subscriptions.
- Examples: RBusEventProvider, RBusEventConsumer
RBus Usage
RBus CLI
The RBuscli is a command-line utility that interacts with the RBus (RDK Bus) system. The RBuscli tool allows developers to register data models, properties, events, and methods, and to interact with them from both provider and consumer perspectives.
Key Uses of RBuscli
Data Model Registration: Register properties, events, and methods to create a hierarchical data model.
Property Management: Set and get property values, enabling communication between different processes.
Event Handling: Subscribe to and log events, which helps in monitoring and debugging.
Method Invocation: Call methods registered by other components, facilitating RPC.
Here is the example usage of RBuscli
NOTE: Below commands are executed in Kirkstone 2023q3 2024q3 build. If dunfell release,it should work with rbus enable.
| Description | Provider | Consumer | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| run RBuscli |
|
| ||||||||||||||
| Register a property |
|
| ||||||||||||||
| set the property |
|
| ||||||||||||||
| get the property |
|
| ||||||||||||||
| set the property (Negative case) |
|
| ||||||||||||||
subscribe event (Negative case). |
|
| ||||||||||||||
| log event |
|
| ||||||||||||||
| subscribe event. |
|
|
RBuscli offers a wide range of commands. To view a complete list, enter help. When you're finished, type quit to exit RBuscli.
Sample Apps
Here is the list of all available sample apps:
| Use Case | Provider | Consumer | Description |
|---|---|---|---|
| Basic RBus Interaction | Provides a basic example of how a provider and consumer interact within RBus. This sample helps in understanding the fundamental operations of RBus. | ||
| Specific Event Handling | Demonstrates how events are generated and consumed in RBus. The provider sends out events, and the consumer listens for and processes these events. | ||
| General Event Handling | Demonstrates how events are registered, published, and consumed in RBus. The provider sends out events when there are active subscriptions, and the consumer listens for and processes these events. It can manage and publish a variety of events, allowing for more dynamic and adaptable event handling. | ||
| Value Change | Illustrates how RBus handles changes in values. The provider detects and sends notifications about value changes, and the consumer reacts to these changes. | ||
| Method Invocation | Demonstrates the invocation of methods in RBus. The provider offers methods that can be called by the consumer, facilitating remote procedure calls. | ||
| Table Management | Shows how table data structures are managed in RBus. The provider manages table data, and the consumer accesses and manipulates this data. |
For additional information, please follow this link RBus.
RBus APIs
Operations | Method | API details | Description |
|---|---|---|---|
Bus Initialization APIs | RBus_open | rbus_errorCode_e RBus_open (busHandle* RBusHandle, char *componentName); | If multiple components share a software process, the first component that calls this API will establishes a new socket connection to the bus broker. All calls to this API will receive a dedicated bus handle for that component. If a component calls this API more than once, any previous busHandle and all previous data element registrations will be canceled. |
RBus_close | rbus_errorCode_e rbus_close (busHandle rbusHandle); | Removes a logical bus connection from a component to the bus. | |
Data Element Registration APIs | RBus_regDataElements | rbus_errorCode_e rbus_regDataElements (busHandle rbusHandle, int numDataElements, rbus_dataElement_t *elements); | A Component uses this API to register one or more named Data Elements (i.e., parameters and/or event names) that will be accessible/ subscribable by other components This also registers the callback functions associated with each data element using the dataElement structure. |
RBus_unregDataElements | rbus_errorCode_e rbus_unregDataElements (busHandle rbusHandle, int numDataElements, rbus_dataElement_t *elements); | A Component uses this API to unregister one or more named Data Elements (i.e., parameters and/or event names) that will no longer be accessible/ subscribable by other components This also registers the callback functions associated with each data element using the dataElement structure. | |
Discovery Related Operations APIs | RBus_discoverComponentName | rbus_errorCode_e rbus_discoverComponentName (busHandle rbusHandle, int numElements, char** elementNames, int *numComponents, char **componentName); | This allows a component to get a list of components that provide a set of data elements name. The requesting component provides the number of data elements and a list of data elements. The bus infrastructure provides the number of components and the component names. |
RBus_discoverComponentDataElements | rbus_errorCode_e rbus_discoverComponentDataElements (busHandle rbusHandle, char* name, rbusBool_t nextLevel, int *numElements, char** elementNames); | This enables a component to get a list of all data elements provided by a component. The requesting component provides component name or all data elements under a "partial path" of an element that ends with "dot". The bus infrastructure provides the number of data elements and the data element name array. | |
Parameters related Operations APIs | RBus_get | rbus_errorCode_e rbus_get(busHandle rbusHandle, rbus_Tlv_t *tlv); | A component uses this to perform a generic get operation on a single variable length parameter |
RBus_getExt | rbus_errorCode_e rbus_getExt(busHandle rbusHandle, int paramCount, char** paramNames, int *numTlvs, rbus_Tlv_t** tlv); | Gets one or more parameter value(s) (TLVs) in a single bus operation | |
RBus_getInt | rbus_errorCode_e rbus_getInt(busHandle rbusHandle, char* paramName, int* paramVal); | A component uses this to perform an integer get operation. | |
RBus_getUint | rbus_errorCode_e rbus_getUint (busHandle rbusHandle, char* paramName, unsigned int* paramVal); | A component uses this to perform a get operation on an unsigned int parameter. | |
RBus_getStr | rbus_errorCode_e rbus_getStr (busHandle rbusHandle, char* paramName, char* paramVal); | A component uses this to perform a get operation on a string parameter. | |
RBus_set | rbus_errorCode_e rbus_set(busHandle rbusHandle, rbus_Tlv_t* tlv, int sessionId, rbusBool_t commit); | A component uses this to perform a set operation for a single explicit parameter and has the option to use delayed (coordinated) commit commands. | |
RBus_setMulti | rbus_errorCode_e rbus_setMulti(busHandle rbusHandle, int numTlvs, rbus_Tlv_t *tlv, int sessionId, rbusBool_t commit); | A component uses this to perform a set operation for multiple parameters at once. | |
RBus_setInt | rbus_errorCode_e rbus_setInt (busHandle rbusHandle, char* paramName, int paramVal); | A component uses this to perform a simple set operation on an integer and commit the operation. | |
RBus_setUint | rbus_errorCode_e rbus_setUint (busHandle rbusHandle, char* paramName, unsigned int paramVal); | A component uses this to perform a simple set operation on an unsigned integer and commit the operation. | |
RBus_setStr | rbus_errorCode_e rbus_setStr (busHandle rbusHandle, char* paramName, char* paramVal); | A component uses this to perform a set operation on a string parameter. | |
Response Building for Get Handler APIs | RBus_initGetResp | rbus_errorCode_e rbus_initGetResp(void *context, int paramCount); | Component's get handlers use this API to initialize "get" response. |
RBus_buildGetRespFromTlv | rbus_errorCode_e rbus_buildGetRespFromTlv(void *context, rbus_Tlv_t tlv); | Component's get handlers use this API to "build" the "get" response by passing a tlv value. | |
RBus_buildGetRespFromEntry | rbus_errorCode_e rbus_buildGetRespFromEntry(void *context, char *paramName, rbus_elementType_e type, void *value, int length); | Component's get handlers use this API to "build" the "get" responseby passing a "value entry". | |
RBus_buildGetRespFromTlvList | rbus_errorCode_e rbus_buildGetRespFromTlvList(void *context, rbus_Tlv_t *tlvList, int length); | Component's get handlers use this API to "build" the "get" responseby passing a list (array) of tlv's. | |
Event Notification APIs | RBusEvent_Subscribe | rbusError_t rbusEvent_Subscribe(rbusHandle_t handle, char const* eventName, rbusEventHandler_t handler, | Components use this API to subscribe for an event |
RBusEvent_Unsubscribe | void* userData); | Components use this API to unsubscribe for an event. | |
RBusEvent_Publish | rbusError_t rbusEvent_Publish(rbusHandle_t handle, rbusEvent_t* eventData); | A component uses this API to publish an event. | |
Table Objects APIs | RBusTable_addRow | rbusError_t rbusTable_addRow(rbusHandle_t handle, char const* tableName, char const* aliasName, uint32_t* instNum); | To add new row to the table |
RBusTable_removeRow | rbusError_t rbusTable_removeRow(rbusHandle_t handle, char const* rowName); | To remove the row from the table | |
RBus_updateTable | rbus_errorCode_e rbus_updateTable(busHandle rbusHandle, char *tableName, rbus_tblAction_e action, char* aliasName); | To update the entry to/from the table | |
Method APIs | RBusMethod_Invoke | rbusError_t rbusMethod_Invoke(rbusHandle_t handle, char const* methodName, rbusObject_t inParams, rbusObject_t* outParams); | Invoke a remote method. |
RBusMethod_InvokeAsync | rbusError_t rbusMethod_InvokeAsync(rbusHandle_t handle, char const* methodName, rbusObject_t inParams, rbusMethodAsyncRespHandler_t callback, int timeout); | Invokes a remote method, non-blocking, with an asynchronous return callback | |
RBusMethod_SendAsyncResponse | rbusError_t rbusMethod_SendAsyncResponse(rbusMethodAsyncHandle_t asyncHandle, rbusError_t error, rbusObject_t outParams); | Send the response to an invoked method | |
Session APIs | RBus_createSession | rbusError_t rbus_createSession(rbusHandle_t handle, uint32_t *pSessionId); | Components use this API to create a new session to set 1 or more parameters and action on table like add/remove rows. |
RBus_getCurrentSession | rbusError_t rbus_getCurrentSession(rbusHandle_t handle, uint32_t *pSessionId); | Components use this API to get the current session to set 1 or more parameters and action on table like add/remove rows. | |
RBus_closeSession | rbusError_t rbus_closeSession(rbusHandle_t handle, uint32_t sessionId); | Components use this API to close the current session that was used to set 1 or more parameter and action on table like add/remove rows | |
Log Handler API | RBus_registerLogHandler | rbusError_t rbus_registerLogHandler(rbusLogHandler logHandler); | A callback handler to get the log messages to application context |
For more information about RBus APIs, please follow this link.
Releases
The latest release of RBus is available here includes support for broadcast listeners, implementation of raw data exchange (TLV) over direct/private connections, and refined handling of event subscriptions.
Overview
Community Forums
Content Tools
Tasks