README.adoc

uProtocol Communication Layer

Table of Contents

• 1. Overview
• 2. uP-L2 Interfaces
• 3. Examples
  • 3.1. Publish a Message
  • 3.2. Invoke a method using RPCClient
  • 3.3. Register and handle rpc request
  • 3.4. Send a notification
  • 3.5. Registering to receive notifications

1. Overview

The following folder contains implementations of the L2 Communication Layer APIs, as per the uProtocol L2 API Specifications.

2. uP-L2 Interfaces

Table 1. Interfaces (uP-L2 Interface)

Interface	Implementation(s)	Description
Publisher	SimplePublisher	Producers API to send publish or notification messages
RpcClient	InMemoryRpcClient	Client interface to invoke a method
RpcServer	InMemoryRpcServer	Server interface to register a listener for incoming RPC requests and automatically send a response
Notifier	SimpleNotifier	Notification communication pattern APIs to notify and register a listener to receive the notifications
All the above	UClient	Single class that Implements all the interfaces above using the various implementations also from above

3. Examples

The uP-L2 interfaces are designed to be used by uEs (applications and services) that rely on the communication patterns to talk with other uEs. The interfaces only require an implementation of uTransport passed by reference to the various APIs to perform the various communication patterns.

Note	Examples below will be using the UClient implementation.

3.1. Publish a Message

transport = # your UTransport instance
#topic to publish
topic : UUri = UUri( ue_id=4, ue_version_major=1, resource_id=0x8000)
publisher : Publisher = UClient(transport)
#send the publish message
publisher.publish(topic)

3.2. Invoke a method using RPCClient

transport = # your UTransport instance

#URI of the method to be invoked
method_uri= UUri(ue_id=10, ue_version_major=1, resource_id=3)
payload = UPayload.pack_to_any(UUri())
options = CallOptions(2000, UPriority.UPRIORITY_CS5)

rpc_client : RpcClient = UClient(transport)
#Returns the asyncio Future with the response payload or raises an exception
with the failure reason as UStatus
await rpc_client.invoke_method(method_uri, payload, options)

3.3. Register and handle rpc request

transport = # your UTransport instance

#URI of the method to be invoked
uri= UUri(ue_id=10, ue_version_major=1, resource_id=3)

#Handler for processing requests
class MyRequestHandler(RequestHandler):
        def handle_request(self, message: UMessage) -> UPayload:
            # If your processing of the request was successful, you return the response message like
            # return UPayload.EMPTY;
            # If your processing of the request failed, you can raise a UStatusException passing the
            # appropriate UCode and message such as:
            # raise UStatusException(UCode.FAILED_PRECONDITION, "Failed to process the request")
            # For this example, we will return an empty response
            return UPayload.EMPTY


rpc_server: RpcServer = UClient(transport)
#Returns the asyncio Future with the response payload or raises an exception
#with the failure reason as UStatus
await rpc_server.register_request_handler(uri, MyRequestHandler())

3.4. Send a notification

transport = # your UTransport instance

#Notification topic
uri : UUri = UUri( ue_id=4, ue_version_major=1, resource_id=0x8000)

#Destination for the notification
destination_uri : UUri = UUri( ue_id=3, ue_version_major=1)


notifier: Notifier = UClient(transport)
# Send the notification (without payload)
await notifier.notify(uri, destination_uri)

3.5. Registering to receive notifications

transport = # your UTransport instance

#Notification topic
uri : UUri = UUri( ue_id=4, ue_version_major=1, resource_id=0x8000)

#Listener to process incoming events on the topic
class MyListener(UListener):
    def on_receive(self, umsg: UMessage) -> None:
        # Handle receiving notifications here
        pass
listener = MyListener()


notifier: Notifier = UClient(transport)
# Register listener to recieve notifications
await notifier.registerNotificationListener(uri, listener)