README.adoc

uProtocol Transport Interface & Data Model

Table of Contents

• 1. Overview
• 2. Examples
  • 2.1. Create Transport
  • 2.2. Build Messages using UMessageBuilder

1. Overview

The following section implements uP-L1 Transport Layer Specifications. The purpose of the transport layer is to wrap communication middlewares into a common interface that allows us to send and receive any kind of uProtocol messages (publish, request, response, notification) over any kind of transport (HTTP, MQTT, WebSockets, etc).

the datamodel is declared in the uProtocol specifications project in the up-core-api folder and this project declares the language specific transport interface (UListener & UTransport) and the builders, serializers, and validators, for the up-core-api data model. .

Below are the list of the classes and interfaces that are part of the uProtocol Transport Interface & Data Model:

Table 1. Transport Interfaces

Class/Interface	Description
UTransport	Interface that defines the methods that a transport middleware must implement in order to be used by the uProtocol library.
UListener	Callback/listener interface to be able to receive messages from a transport.
UMessageBuilder	Interface that simply builds request, response, publish, and defines the methods that a message builder must implement in order to be used by the uProtocol library.
UAttributesValidator	uProtocol Attributes validator that ensures that the publish, notification, request, and response messages are built with the correct information.

2. Examples

2.1. Create Transport

class HappyUTransport(UTransport):
    async def close(self) -> None:
        pass

    async def send(self, message):
        return UStatus(code=UCode.INVALID_ARGUMENT if message is None else UCode.OK)

    async def register_listener(self, source_filter: UUri, listener: UListener, sink_filter: UUri = None) -> UStatus:
        listener.on_receive(UMessage())
        return UStatus(code=UCode.OK)

    async def unregister_listener(self, source_filter: UUri, listener, sink_filter: UUri = None):
        return UStatus(code=UCode.OK)

    def get_source(self):
        return UUri()

2.2. Build Messages using UMessageBuilder

2.2.1. Build Publish Message

topic : UUri = UUri( ue_id=4, ue_version_major=1, resource_id=0x8000)
UMessageBuilder.publish(topic).build()

# to add payload, pack your proto message in UPayload
# to pack UUri()
UMessageBuilder.publish(topic).build_from_upayload(UPayload.pack(UUri()))

2.2.2. Build Notification Message

topic : UUri = UUri( ue_id=4, ue_version_major=1, resource_id=0x8000)
destination_uri : UUri = UUri( ue_id=3, ue_version_major=1)

UMessageBuilder.notification(topic, destination).build()

2.2.3. Build Request Message

source : UUri = UUri( ue_id=4, ue_version_major=1, resource_id=0x8000)
sink : UUri = UUri( ue_id=3, ue_version_major=1)
#1000 is ttl here
UMessageBuilder.request(source, sink, 1000).build()

2.2.4. Build Response Message

source : UUri = UUri( ue_id=4, ue_version_major=1, resource_id=0x8000)
sink : UUri = UUri( ue_id=3, ue_version_major=1)
reqid : UUID = Factories.UPROTOCOL.create()
UMessageBuilder.response(source, sink, reqid).build()

2.2.5. Build Response Message from Request

UMessageBuilder.response_for_request(request.attributes).build()