# Uconnect Global Vehicle to Mobile API's

#### Version 1.0

#### Table of Contents

## Introduction

The FCA Uconnect Global API's define a standard data communication protocol between the Telematics Unit in the vehicle and the Brought In Mobile Device (BIMD). The in-vehicle unit is primarily a Head Unit (HU) with BlueTooth, USB, and/or WiFi connectivity with the BIMD.

The primary objective of this API is to create interoperability between the FCA regions including APAC, EMEA, LATAM, and NAFTA which with proper adoption will result in efficiency improvements and cost reductions as platforms become more global. Additionally, the API will improve the FCA Connected Vehicle Platform design for performance, scalability, flexibility, security, maintainability, and cost effectiveness.

The core of the API is based on the sending of Protocol Buffer messages over a TLS-PSK secured command and control channel established between the HU and the BIMD.

## Global_V2M_Uconnect_CommAndCont.proto (Version 1.0)

###

###

###

    The  proto is utilized to establish Tunnel Connection and stop Connection.

      UconnectAnyV2M
        |
        |---- EstablishRemoteConnection
        |
        |---- EndConnection
        |
        |---- EstablishAcknowledgement
      Change Log

    	VersionDateNotes

    	1.12017-08-09Update Establish Connection interface
    	1.02017-07-13Release of initial Proto

    List of MQTT Topics

    	FlowTypeTopic Name

      BIMD send to VehiclePublishtopic/${iot:ClientId}/CONN
    	 BIMD receive from VehicleSubscribetopic/CONN/#
    	 Vehicle send to BIMD Publishtopic/CONN/${iot:ClientId}
    	 Vehicle receive from BIMD Subscribetopic/${iot:ClientId}/#

    Data FlowThe following sequence diagram depicts the flow of messages between the TBM/HU and the BIMD:
    	SequenceTitleRoleMessageTopicDescription

    1.Connection EventTBM/HUThe in-vehicle Connection event which triggers the client device to send an EstablishConnection message  to the BIMD.
    2.Assign MessageIdTBM/HUThe client generates the messageId for the message by incrementing a sequence counter.
    3.Send EstablishRemoteConnection MessageTBM/HUEstablishRemoteConnection/CONN/${iot:ClientId}The client populates the EstablishRemoteConnection Message with the required elements and publishes to the Connection topic.
    4.Process MessageBIMDThe BIMD processes the message and generates an EstablishAcknowledgement Message with the status and the correlationId set to the messageId from the received EstablishRemoteConnection Message.
    5.Send EstablishAcknowledgement MessageBIMDEstablishAcknowledgement${iot:ClientId}/CONNThe service publishes the response message to the Connection topic for the client to receive.
    6.Process MessageTBM/HUThe client receives the message and verifies the correlationId matches the messageId of the sent request.
    8.Send EndConnection MessageTBM/HUEndConnection${iot:ClientId}/CONNThe Client publishes the EndConnection message to stop the Connection to  the Connection topic for the BIMD to receive.
    9.Process MessageTBM/HUThe BIMD receives the message and verifies the correlationId matches the messageId of the initially sent request and stops the  connection.

### EstablishRemoteConnection

This message is to establish Tunnel Connection from V2M.

#### EstablishRemoteConnection Example Message:

``

timestamp: 1488574019636

messageId: 1

messages

{

[com.fca.uconnect.global.establishRemoteConnection]

{

remoteHostURL: "host"

remotePort: 8080

localPort: 80

priority: 1

}

}

Field | Type | Label | Description
remoteHostURL | string | optional | The target host URL to establish a connection for tcp/ip forwarding.
remotePort | int32 | optional | The port of the service running on the remote host.
localPort | int32 | optional | The desired local port which will be used forward to the remote host. The acknowledgement will provide the actual port.
priority | int32 | optional | Placeholder for future capability to prioritize channels.
parameters | EstablishRemoteConnection.ParametersEntry | repeated | Placeholder for future requirements for additional parameters.

### EstablishRemoteConnection.ParametersEntry

Field | Type | Label | Description
key | string | optional |
value | string | optional |

### EstablishAcknowledgement

This message is to Acknowledge the Connection Establishment.

#### EstablishAcknowledgement Example Message:

``

timestamp: 1488574019636

messageId: 2

correlationId: 1

messages

{

[com.fca.uconnect.global.establishAcknowledgement]

{

status: SUCCESS

connectionId: 123233414

localPort: 3334

}

}

Field | Type | Label | Description
status | EstablishAcknowledgement.StatusEnum | optional | Status indicating success or failure.
reason | EstablishAcknowledgement.ReasonEnum | optional | Status failure reason code.
connectionId | int32 | optional | A generated id to reference the connection.
localPort | int32 | optional | The actual local port which will be used forward to the remote host.

### EstablishAcknowledgement.StatusEnum

Name | Number | Description
SUCCESS | 0 |
FAILURE | 1 |

### EstablishAcknowledgement.ReasonEnum

Name | Number | Description
FAILED | 0 |
INVALID_PORT | 1 |
PORT_ALREADY_IN_USE | 2 |
INVALID_HOST | 3 |
INVALID_PRIORITY | 4 |

### EndConnection

This message is to end the Tunnel Connection.

#### EndConnection Example Message:

``

timestamp: 1488574019636

messageId: 1

messages

{

[com.fca.uconnect.global.endConnection]

{

connectionId: 123456

}

}

Field | Type | Label | Description
connectionId | int32 | optional |

### Where to Find the ProtoBuf File

Click here to download Protobuf.

### Example Code for Global_V2M_Uconnect_CommAndCont.proto

Here are some code samples to demonstrate how to create, send and receive messages. This tutorial shows how to

- Define .proto
- Compiling Protobuf
- Example Code

### Define .proto

Start with .proto file. Add required messages and elements to each message.

### Compiling Protobuf

Download Protobuf Compiler here and run the following command.

protoc --java_out=. Global_V2M_Uconnect_CommAndCont.proto

which then generates java file in package that you specified in .proto.

### Example Code

Once Proto file is created and compiled, Its time to write code for MQTT Connection, publish and subscribe topics from Client and Service.

See the FAQ for setting up a Java project to execute an example client. Once the protobuf file has been created, compiled, and imported into your Java project, you can use the following example code in your project:

## Global_V2M_Uconnect_Common.proto (Version 1.0)

###

    The common proto is utilized to wrap one or more messages in an extensible manner for delivery between the client
    and services.  This proto also includes common header elements necessary to implement required messaging patterns.
    UconnectMessageV2M KeepAliveMessage KeepAliveAckMessage UconnectAny   Change Log

    	VersionDateNotes

    	1.12017-08-07Update KeepAlive
    	1.02017-06-01Release of initial Proto

### UconnectMessageV2M

Field | Type | Label | Description
timestamp | int64 | optional | The current system time on the platform when the message is generated. NOTE: The SDP/TSP will provide a network time service based on NTP to augment the GPS time captured in the vehicle.
sessionId | bytes | optional | may contain any arbitrary sequence of bytes. Intended for implementations where parties to a session need to share a session identifier. Implementations that do so will be able to use sessionId and messageId to correlate logged messages for diagnostic/debug purposes.
messageId | int32 | optional | Unique message id also utilized as a correlation id for responses.
correlationId | int32 | optional | Must only be set from the messageId of a received message. If there is not a received message being responded to, do not set any value other than the default. Initiators of interactions should never set correlationId, it is for point to point request/response only.

### KeepAliveMessage

The KeepAliveMessage provides a lightweight keep alive message to support monitoring the connection between the Vehicle and Mobile Device.

The vehicle software component supporting BIMD connectivity shall periodically send a KeepAliveMessage and monitor for a response.

Field | Type | Label | Description
messageId | int32 | optional | Unique message id also utilized as a correlation id for responses.
timestamp | int64 | optional | The milliseconds since (Jan 1, 1970 00:00:00 UTC) when the message is created. Should come from the system clock of the sender.

### KeepAliveAckMessage

The KeepAliveAckMessage provides a lightweight response to a keep alive message originating from the vehicle.

The Mobile Device software component shall return an Ack message in reponse to every received KeepAliveMessage.

Field | Type | Label | Description
correlationId | int32 | optional | Must be set from the messageId of the received message.
timestamp | int64 | optional | The milliseconds since (Jan 1, 1970 00:00:00 UTC) when the message is created. Should come from the system clock of the sender.

### UconnectAnyV2M

The UconnectAny message allows for protocol buffer extensions so feature specific messages are decoupled from the top level message. It is a placeholder to allow a repeated set of extensions.

Field | Type | Label | Description

### Where to Find the ProtoBuf File

Click here to download Protobuf.

### Example Code for Global_V2M_Uconnect_Common.proto

Here are some code samples to demonstrate how to create, send and receive messages. This tutorial shows how to

- Define .proto
- Compiling Protobuf
- Example Code

### Define .proto

Start with .proto file. Add required messages and elements to each message.

### Compiling Protobuf

Download Protobuf Compiler here and run the following command.

protoc --java_out=. Global_V2M_Uconnect_Common.proto

which then generates java file in package that you specified in .proto.

### Example Code

Once Proto file is created and compiled, Its time to write code for MQTT Connection, publish and subscribe topics from Client and Service.

See the FAQ for setting up a Java project to execute an example client. Once the protobuf file has been created, compiled, and imported into your Java project, you can use the following example code in your project:

## Scalar Value Types

.proto Type | Notes | C++ Type | Java Type | Python Type
double |  | double | double | float
float |  | float | float | float
int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int
int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long
uint32 | Uses variable-length encoding. | uint32 | int | int/long
uint64 | Uses variable-length encoding. | uint64 | long | int/long
sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int
sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long
fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int
fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long
sfixed32 | Always four bytes. | int32 | int | int
sfixed64 | Always eight bytes. | int64 | long | int/long
bool |  | bool | boolean | boolean
string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode
bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str