package uprotocol.v1

Get desktop application:
View/edit binary Protocol Buffers messages

File Checksum

Used in: File

• ChecksumType type = 1

  Type of Checksum

• bytes value = 2

  The checksum value

Checksum type

Used in: Checksum

• CHECKSUM_TYPE_UNSPECIFIED = 0

  Unspecified

• CHECKSUM_TYPE_MD5 = 1

  MD5SUM

• CHECKSUM_TYPE_SHA1 = 2

  SHA1SUM

File Message Files can be attached to uProtocol in the headers

Used in: FileBatch

• string name = 1

  RFC8089 formatted filename URI

• optional uint64 size = 2

  File size attribute

• optional Checksum checksum = 3

  Optional file checksum

Collection of Files (batch)

• repeated File files = 1

  Repeated list of 0 to n attached files

Metadata describing a particular message's purpose, content and processing requirements. Each type of message is described by a set of mandatory and optional attributes.

Used in: UMessage

• optional UUID id = 1

  A unique message identifier.

• UMessageType type = 2

  This message's type which also indicates its purpose and determines contraints on the other properties.

• optional UUri source = 3

  The origin (address) of this message.

• optional UUri sink = 4

  The destination (address) of this message.

• UPriority priority = 5

  The QoS level that this message should be processed/delivered with.

• optional uint32 ttl = 6

  The amount of time (in milliseconds) after which this message MUST NOT be delivered/processed anymore.

• optional uint32 permission_level = 7

  The service consumer's permission level.

• optional UCode commstatus = 8

  A UCode indicating an error that has occurred during the delivery of either an RPC Request or Response message.

• optional UUID reqid = 9

  The identifier that a service consumer can use to correlate an RPC Repsonse message with its RPC Request.

• optional string token = 10

  The service consumer's access token.

• optional string traceparent = 11

  A tracing identifier to use for correlating messages across the system. Intended to be compatible with https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/distributed-tracing.md

• UPayloadFormat payload_format = 12

  The format for the data stored in the UMessage.

Canonical Error codes for uProtocol APIs

Used in: UAttributes, UStatus

• OK = 0

  Completes successfully

• CANCELLED = 1

  Operation has been cancelled by the caller

• UNKNOWN = 2

  An unknown (but not critical) error has occurred

• INVALID_ARGUMENT = 3

  Passed arguments are invalid (ex. improperly formatted)

• DEADLINE_EXCEEDED = 4

  Operation has expired (timeout)

• NOT_FOUND = 5

  Operation cannot be completed because the requested entity was not found (ex. database lookup and the data is not found) Calling uEntity *MAY* retry the operation with back-off

• ALREADY_EXISTS = 6

  The calling uEntity requested to add/create something that already exists (ex. add to a database something that is already there)

• PERMISSION_DENIED = 7

  The calling uEntity is authenticated but not permitted to call the API

• UNAUTHENTICATED = 16

  The calling uEntity does not have valid authentication credentials for the API

• RESOURCE_EXHAUSTED = 8

  The resource being accessed has been exhausted (ex. out of disk space, etc...)

• FAILED_PRECONDITION = 9

  The system (service) is in a state that it cannot handle the request Calling uEntities *SHOULD NOT* retry till the system state has been corrected

• ABORTED = 10

  The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort Calling uEntities *MAY* retry but at a higher frequency than UNAVAILABLE

• OUT_OF_RANGE = 11

  A caller would typically iterating through the results from said API and can is expected to detect the end of the results (out of range)

• UNIMPLEMENTED = 12

  Part or all of the requested operation has not been implemented yet

• INTERNAL = 13

  A serious internal error has not described by a known error code

• UNAVAILABLE = 14

  The operation is currently unavailable Calling uEntities *MAY* retry with back-off

• DATA_LOSS = 15

  When an unrecoverable data loss or corruption has occurred

UMessage is the top-level message type for the uProtocol. It contains a header (UAttributes), and payload and is a way of representing a message that would be sent between two uEntities.

Used in: core.utwin.v2.MessageResponse

• optional UAttributes attributes = 1

  uProtocol mandatory and optional attributes

• optional bytes payload = 2

  Optional message payload

uProtocol defines different types of messages. Using the message type, validation can be performed to ensure transport validity of the data in the {@link UAttributes}. The "up-" prefix used in the uprotocol.ce_name options has been introduced to allow distinguishing between existing CloudEvents being exchanged by legacy systems using a predecessor of Eclipse uProtocol and CloudEvents conforming to the mapping rules defined in the Eclipse uProtocol specification.

Used in: UAttributes

• UMESSAGE_TYPE_UNSPECIFIED = 0

  Unspecified message type

• UMESSAGE_TYPE_PUBLISH = 1

  Publish A message that is used to notify all interested consumers of an event that has occurred.

• UMESSAGE_TYPE_REQUEST = 2

  RPC Request A message that is used by a service consumer to invoke one of a service provider's methods with some input data, expecting the service provider to reply with a response message.

• UMESSAGE_TYPE_RESPONSE = 3

  RPC Response A message that is used by a service provider to send the outcome of processing a request message from a servcice consumer.

• UMESSAGE_TYPE_NOTIFICATION = 4

  Notification A message that is used to inform a specific consumer about an event that has occurred.

The format for the data stored in the UMessage.

Used in: UAttributes

• UPAYLOAD_FORMAT_UNSPECIFIED = 0

  Payload format is unknown.

• UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY = 1

  Payload is an Any protobuf message that contains the packed payload

• UPAYLOAD_FORMAT_PROTOBUF = 2

  Protobuf serialization format

• UPAYLOAD_FORMAT_JSON = 3

  JSON serialization format

• UPAYLOAD_FORMAT_SOMEIP = 4

  Basic SOME/IP serialization format

• UPAYLOAD_FORMAT_SOMEIP_TLV = 5

  SOME/IP TLV format

• UPAYLOAD_FORMAT_RAW = 6

  RAW (binary) format

• UPAYLOAD_FORMAT_TEXT = 7

  Text format

• UPAYLOAD_FORMAT_SHM = 8

  Shared memory format

Message priority levels.

Used in: UAttributes

• UPRIORITY_UNSPECIFIED = 0

  Unspecified priority

• UPRIORITY_CS0 = 1

  Low Priority. No bandwidth assurance such as File Transfer.

• UPRIORITY_CS1 = 2

  Standard, undifferentiated application such as General (unclassified).

• UPRIORITY_CS2 = 3

  Operations, Administration, and Management such as Streamer messages (sub, connect, etc…)

• UPRIORITY_CS3 = 4

  Multimedia streaming such as Video Streaming

• UPRIORITY_CS4 = 5

  Real-time interactive such as High priority (rpc events)

• UPRIORITY_CS5 = 6

  Signaling such as Important

• UPRIORITY_CS6 = 7

  Network control such as Safety Critical

uProtocol Error model for all uProtocol APIs that is loosly based off google.rpc.Status

Used in: core.utwin.v2.MessageResponse

• UCode code = 1

  The status code.

• optional string message = 2

  A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the details field, or localized by the client.

• repeated google.protobuf.Any details = 3

  A list of messages that carry the error details. There is a common set of message types for APIs to use.

The UUID datamodel per https://www.rfc-editor.org/rfc/rfc9562[RFC 9562]

Used in: UAttributes

• fixed64 msb = 1

  Most significant bits

• fixed64 lsb = 2

  Least significant bits

Data model definition for source and destination addressing of messages sent to/from devices, services, methods, topics, etc...

Used in: core.udiscovery.v3.FindServicesRequest, core.udiscovery.v3.GetServiceTopicsRequest, core.udiscovery.v3.ServiceTopicInfo, core.usubscription.v3.FetchSubscribersRequest, core.usubscription.v3.FetchSubscriptionsRequest, core.usubscription.v3.NotificationsRequest, core.usubscription.v3.SubscriberInfo, core.usubscription.v3.Subscription, core.usubscription.v3.SubscriptionRequest, core.usubscription.v3.SubscriptionResponse, core.usubscription.v3.UnsubscribeRequest, core.usubscription.v3.Update, core.utwin.v2.MessageResponse, UAttributes, UUriBatch

• string authority_name = 1

  Authority Name. Could be the host name, ip address, device & domain names, etc..

• uint32 ue_id = 2

  Software Entity (uEntity) Identifiers.

• uint32 ue_version_major = 3

  Software Entity (uEntity) major version number.

• uint32 resource_id = 4

  uEntity resource id. Identifier used to represent either a method, publish topic, or notification topic.

List of URIs that can be used for batching APIs.

Used in: core.udiscovery.v3.FindServicesResponse, core.utwin.v2.GetLastMessagesRequest

• repeated UUri uris = 1