up-l3

Application Layer (uP-L3)

Table of Contents

• 1. Architecture Patterns
• 2. Core uProtocol uEs
• 3. Name & Number Registry
  • 3.1. uEntity ID Ranges
  • 3.2. Names

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)

SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation

See the NOTICE file(s) distributed with this work for additional
information regarding copyright ownership.

This program and the accompanying materials are made available under
the terms of the Apache License Version 2.0 which is available at
https://www.apache.org/licenses/LICENSE-2.0

SPDX-FileType: DOCUMENTATION
SPDX-License-Identifier: Apache-2.0

Application layer, also known as the business logic layer, is responsible for declaration interfaces between clients and servers for features and functions, the API layer that defines the methods and topics served by a service.

In this specification we will also define core uProtocol business logic (APIs) such as subscription management, discovery, and digital twin. These interfaces are declared once, used everywhere so that the mental model for developers is consistent across different heterogeneous systems.

1. Architecture Patterns

uProtocol supports the architecture patterns defined in the table below to implement the majority of use cases that could be required for business logic communication between clients and services.

Table 1. Architecture Patterns

Architecture Pattern	Delivery Policy	Description	Requirements
RPC	At-least-once	When uE requires acknowledgement from the receiver	If the client-side business logic requires retry policy, it MUST implement the retry policy Server-side business logic MUST implement Idempotency for remote procedural calls Dispatchers that are unable to deliver req.v1, MUST generate a delivery failure res.v1 and send it back to the Sender uE
Publication	At-most-once	When uE wishes to publish an CE to multiple consumers (a.k.a. "fire & forget")	Dispatcher MUST provide access to CEs that have failed to be delivered (DLT defined in a later section), for both the Sender and/or Receiver uE business logic
Notification	At-most-once	When a uE wishes to notify a specific uE (a.k.a a publication with a destination)

2. Core uProtocol uEs

This special purpose built uEs are required to implement uProtocol and must be present on each uDevice.

Table 2. Core uEs

uE	Ver	Description
uSubscription	v3	Subscription management service that is responsible for managing subscriptions between uEs to realize the publisher/subscriber design pattern.
uDiscovery	v3	Discovery of uThings locally, within a domain, and throughout the network. Supports URI resolution (to find where something is located)
uTwin	v2	Local cache of published events

3. Name & Number Registry

uProtocol URIs (UUri) contain a uEntity Identifier (ue_id) to refer to a particular service type. The ue_id is a 32 bit unsigned integer of which the least significant 16 bit are used to indicate the service type.

The following section defines sub-ranges of the 16 bit service type address space to be used for different purposes. This will make sure that custom service types defined in a private scope can co-exist with standard uProtocol service types without ambiguities and interference.

3.1. uEntity ID Ranges

Table 3. Reserved ue_ids

ID Range	Purpose
0x0000 - 0x00FF	Eclipse uProtocol services
0x0100 - 0x0FFF	COVESA uServices
0x1000 - 0x7FFF	Future use
0x8000 - 0xFFFE	Vendor specific services
0xFFFF	Reserved

• uProtocol uE names and numbers MUST be declared in protos and added to up-core-api.

3.2. Names

• uProtocol defined names MUST have core. prefix

• Vendor specific uE names SHOULD have the vendor name in the prefix, ex. volvo., 'bmw', etc…​