Loading

Uli SDK

Terminologies

1. Terminologies

To explain the Uli SDK, the following notions are descripted in detail:

1.1 Service

Service is the behavior that provides well-defined functions. It can be described as a state machine that responds to messages or events in the context of the current state.

1.2 Message

Message is to be sent between client and server. Server receives messages and then performs tasks, transitions its state, or raises events.

1.3 Internal Event

Internal event is raised by a service to notify other services in the same component that something significant has happened.

1.4 State Machine

State Machine is to describe the behavior of the Service. State Machine defines the input and output messages and internal events, and state transitions caused by messages and internal events.

1.5 Component (Comp)

Component, Comp in short hand, is a software unit that implements a set of related services. A component is identified by Component ID. There are following types of the component: 0) UNKNOWN, 1) REGULAR – nothing special, and 2) SAFETY_CRITICAL – comp that could raise emergency condition when it is not functioning proper.

1.6 Node

Node is a computing module that hosts a set of related components. Node is identified by Node ID.

1.7 Subsystem

Subsystem consists of one or more nodes. One of the nodes is designated as Subsystem Node, which has the Node ID=1 and responsible for assigning ID to other nodes. For example, in Figure 1 Network Topologies shows an example of 4 subsystems and their nodes. Note that a subsystem node have external network interfaces (Orange Line) to other subsystems and internal network interfaces (thin black line) to the nodes within the same subsystem.

1.8 Comp Address

Comp Address is a tuple of 3 fields: (Subsystem ID, Node ID, Comp ID). Here is the scheme of the Address:


Name Type Range
Subsystem ID 4 byte unsigned integer 0x00000001 –
0xFFFFFFFE
0x00000000 – unknown
0xFFFFFFFF – wild card
Node ID 2 byte unsigned short 0x0001 – 0xFFFE
0x0000 – unknown
0xFFFF – wild card
Comp ID 1 byte unsigned short 0x01 – 0xFE
0x00 – unknown
0xFF – wild card

Fields in the Address can have wild card values of 0xFFFFFFFF or 0xFFFF. The wild card value in a field matches any number of that field. For example, Subsystem ID = 0xFFFFFFFF matches all the subsystems. By the same token, Node ID = 0xFFFF matches all the nodes and Component ID = 0xFF matches all the components. The wild card is useful to broadcast messages to all the subsystems, nodes, and components.

1.9 Relationship

The graph below shows the relationships between subsystems, nodes, components, services, state machine, messages, and internal events. The component address (254, 1, 33) implements a client service of the mobility driver. The component accesses the mobility drive service implemented in the component address (10, 2, 33).



1.10 Resource

A service may have resources accessible by other means than Uli SDK’s messaging. For example: A video service provides rtsp streams that clients may access the streams using video playbacks.

Services can register resources to the Subsystem Manager, where clients are able to discovery them.

1.11 Subsystem Manager

A component in the Subsystem Node is designated as Subsystem Manager, which has a registry that keeps records of 1) services and 2) resources of components in all nodes of this subsystem. The Subsystem Manager component also includes Status Monitor service, that monitors the status from all the components in the subsystem.

The Subsystem Manager is responsible for assign ID to the nodes that does not have a static ID. The Node Manager service requests ID once received Subsystem Manager Ready messages.

The Node that hosts Subsystem Manager always has static Node ID=1.

1.12 Node Manager

A component in a node is designated as Node Manager, which is assigned with component ID=1. The Node Manager is responsible for routing messages on the behalf of the components in the node.

The Node Manager uses UDP to communicate with other nodes and subsystems. Internally, the Node Manager uses Local Socket for communicating with the components in the node.

1.13 Message Format

A message consists of two field: Header and Payload:


Field # Name
1 Header
2 Payload

Uli SDK uses Cap’n Proto, https://capnproto.org/, to encode/decode messages.

1.13.1 Header


Field # Name Type Definition
1 Uuid 8 byte Message identifier
2 Partition string Partition where the message belongs to
3 Acknak 1 byte, unsigned integer 0 = no ack, 1=ack needed, 2=ack message
4 Priority 1 byte, unsigned integer
5 Message ID 8 byte, unsigned integer Identifier of the schema of the message
6 Sender ID 8 byte, Comp Address
7 Receiver ID 8 byte, Comp Address
8 Acquire Time 8 byte, unsigned integer Count in nano second since Epoch
9 Publish Time 8 byte, unsigned integer Count in nano second since Epoch

Uuid

The universal identifier of this message.

Partition

Identifier of the partition the message should be processed. Components that belong to a partition, only process messages for the partition.

This feature allows reconfiguration of nodes and components without reconfiguring the network.

Acknak

Indication whether ack message is requested.

Priority

Currently, only one level.

Message ID

Identifies the schema of the message encoded in the payload.

Sender ID

The component address where message is sent. The address can be all 0’s that indicates the component address of the sender is not yet assigned.

Receiver ID

1.13.2 Payload

Payload is the structure of the message. When a message is received, Message ID from header is decoded and the schema of the message is identified. The payload then decoded.

1.14 Messaging

A message is sent to receiver components specified by the receiver address tuple in the message header. Using wild-card, the message can be sent to more than one receivers. Here are different options:

1.14.1 unicast

No wild-card in the receiver address. The message is sent to the component whose address is specified by the receiver ID field of the message.

1.14.2 node-broadcast

The receiver ID in message header has specific Subsystem ID and Node ID, but component ID is wild-card. For example: (3, 2, 0xFFFF) that the message is sent to all components in the Node ID=2 and Subsystem ID=3.

1.14.3 subsystem-broadcast

The receiver ID in message header has specific Subsystem ID, but Node ID is wild-card. For example: (3, 0xFFFF, 0xFF) to all the nodes and components in the subsystem ID=3, and the address (3, 0xFFFF, 1) is destinated to the Node Manager of all the nodes in the subsystem ID=3.

1.14.4 global-broadcast

The receiver ID in the message header has wild-card Subsystem ID. For example: (0xFFFFFFFF, 1, 1) to Subsystem Managers of all the Subsystems.

1.15 Dynamic ID Assignment

1.15.1 Subsystem ID assignment

The subsystem ID can be assigned statically that the Subsystem Manager is configured with a pre-determined subsystem ID.

The subsystem ID can be also assigned dynamically that Subsystem Manager globally broadcasts ID Request messages to ID Allocator. The ID Request messages contains unique identifier (UUID) for the request.

The ID Allocator responses by global-broadcasting ID Granted messages that contains valid subsystem ID for that Subsystem and the unique identifier of the request from the Subsystem Manager.

Once having resolved the ID, regardless static or dynamic, Subsystem Manager periodically subsystem-broadcasts Subsystem Ready with valid subsystem ID to all the nodes of the subsystem.

In the case that Subsystem Manager dynamically obtained its ID, it needs to periodically Query Allocated ID to the ID Allocator. The Subsystem Manager checks if its ID is valid on the Report Allocated ID from the ID Allocator.

Refer to Uli SDK Users’ Guide for details of the activities.

1.15.2 Node ID assignment

The node ID can be assigned statically that the Node Manager is configure with a pre-determined node ID.

The node ID can be also assigned dynamically that Node Manager sends Node ID Request messages to the Subsystem Manager after received Subsystem Manager Ready. Subsystem Manager responses by subsystem-broadcasting Node ID Allocate messages that contains valid node ID for that Node Manager.

Node Manager periodically node-broadcasts Node Manager Ready with valid node ID to the components in its node once it obtained valid node ID.

Similarly, in the case that a Node Manager, that obtains its ID dynamically, stops receiving Subsystem Manager Ready for the period of ID Allocator Timeout, it should forget the obtained Node ID and begins the process of requesting for Node ID again. Also, since the Node Manager does not have valid ID, it should stop broadcasting Node Manager Ready messages.

Without receiving Node Manager Ready, Component Transport service of a component should not send or process received messages.

Refer to Uli SDK Users’ Guide for details of the activities.