Skip to content

TLP Message Protocol

Overview

The TLP Message Protocol (TLP-MP) provides a "request-response" and broadcast message transmission mechanism for the software components in the TLP system.

In the TLP system, software components need inter-process and inter-network service invocation mechanisms, and software components need to asynchronously notify events generated by multiple other software components. TLP-MP uses "publish-subscribe" operations on the message bus to meet these two requirements:

  • When a software component needs to provide services externally, it can listen to all messages sent to the path by subscribing to an address we call the message path;
  • When a software component needs to call a published service, it can send a request message to a message path, and expect to receive the call result on the response message path that it monitors;
  • When a software component broadcasts an event on a message path, all software components subscribed to the message path will receive the broadcast event message.

In order to control the transmission of messages, TLP-MP regards each message path as a resource address, and defines the following types of operation for request messages, so that the access control component can control access according to the address and operation type:

  • GET operation, indicating that the purpose of the request operation is to read the content of the resource and will not change the content of the resource;
  • PUT operation, indicating that the purpose of the requested operation is to update the resource content to the provided data content;
  • POST operation, indicating that the purpose of the request operation is to create a new sub-item or partially modify the content of the resource;
  • The DELETE operation indicates that the purpose of the requested operation is to delete the resource.

Message Format

The message in TLP-MP consists of message address, message header and message body:

  • The message address uniquely determines the destination of the "request-response" message (that is, the address of the receiver), or the source of the broadcast message (that is, the address of the sender);
  • The message header contains meta information related to the message, such as the operation type and sender of the "request-response" message;
  • The message body contains the data that the software component wants to pass to other components.

Message Address

The message address is a string of characters separated by ‘/’, the format is:

/MP/1.0/<controllerId>/(events|services|components)/[...]

Information

<controllerId> is the unique identifier of the controller in a controller network.

In TLP-MP, there are 5 types of addresses:

  • Public service address. The default service in the system subscribes to a message address and responds to requests sent to the subscribed address in real time. The format is:
/MP/1.0/<controllerId>/services/<serviceId>/...

Information

  • <serviceId> is the unique identifier of the service, and the same service has the same serviceId.
  • The default service refers to the implementation of the service that is accessed by default when multiple software components provide services with the same serviceId. When there is only one software component in the system that provides the service represented by a certain serviceId, the service is automatically regarded as the default service. When there are multiple choices, the default service is usually determined by the administrator.
  • Public broadcast address, all event messages of default services are sent from the public broadcast address. Subscribing to a public broadcast address means that when an event is sent out on that address, the subscriber will receive the message. The format of the public broadcast address is:
/MP/1.0/<controllerId>/events/<serviceId>/...
  • The private service address of the component, used to access non-default services. The software component that sends the request must know the ID of the component that provides the service. The format is:
/MP/1.0/<controllerId>/components/<componentId>/services/<serviceId>/...

Information

<componentId> is the unique identifier of the software component within the scope of the controller.

  • The private broadcast address of the component, used to send the broadcast of the private service of the software component. The format is:
/MP/1.0/<controllerId>/components/<componentId>/events/<serviceId>/...
  • The response address, used to receive the response to the service request. The format is:
/MP/1.0/<controllerId>/components/<componentId>/results/<serviceId>/...

Message Header

The message header of TLP-MP contains message-related information, which has been embodied in the form of key-value pairs. Each key-value pair is called a field, and the message header can contain multiple fields.

Header of The Request Message

Field Name Value Type Description
method GET|PUT|POST|DELETE Type of operation
sender String The componentId of the software component that sent the request message
contentType Media Types Encoding of the message body
correlation Integer A unique number corresponding to the request and response message

Example

{
    "method": "GET",
    "sender": "Xn2iZkj9",
    "correlation": 23123243,
    "contentType": "applications/cbor"
}

Header of The Response Message

Field Name Value Type Description
method GET|PUT|POST|DELETE Type of operation
sender String The componentId of the software component that sent the request message
contentType Media Types Encoding of the message body
correlation Integer A unique number corresponding to the request and response message
code RFC 7231 Response Status Codes Response code for the execution of the request
message String A textual description of the execution of the request

Example

{
  "method": "GET",
  "sender": "Xn2i2kak",
  "correlation": 23123243,
  "contentType": "applications/cbor",
  "code": 200,
  "message": "Success"
}

Header of The Event Message

Field Name Value Type Description
event String Name of the event
contentType Media Types Encoding of the message body

Example

{
  "event": "BridgePresence",
  "contentType": "applications/cbor"
}

Message Body

The message body of TLP-MP is used to carry the content of the message, and its encoding format is determined by the contentType in the message header.

Bearer Protocol

MQTT

TLP-MP supports MQTT 3.1.1 as the bearer protocol:

  • The message address is the Topic of the MQTT message;
  • The message header is encoded in CBOR and put into the Payload of the MQTT message;
  • The message body uses content as the field name, and is put into the Payload of the MQTT message together with the field of the message header.