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.
The proto is utilized to establish Tunnel Connection and stop Connection.
UconnectAnyV2M | |---- EstablishRemoteConnection | |---- EndConnection | |---- EstablishAcknowledgement
Change Log
| Version | Date | Notes |
|---|---|---|
| 1.1 | 2017-08-09 | Update Establish Connection interface |
| 1.0 | 2017-07-13 | Release of initial Proto |
| Flow | Type | Topic Name |
| BIMD send to Vehicle | Publish | topic/${iot:ClientId}/CONN |
| BIMD receive from Vehicle | Subscribe | topic/CONN/# |
| Vehicle send to BIMD | Publish | topic/CONN/${iot:ClientId} |
| Vehicle receive from BIMD | Subscribe | topic/${iot:ClientId}/# |
The following sequence diagram depicts the flow of messages between the TBM/HU and the BIMD:
| Sequence | Title | Role | Message | Topic | Description |
| 1. | Connection Event | TBM/HU | The in-vehicle Connection event which triggers the client device to send an EstablishConnection message to the BIMD. | ||
| 2. | Assign MessageId | TBM/HU | The client generates the messageId for the message by incrementing a sequence counter. | ||
| 3. | Send EstablishRemoteConnection Message | TBM/HU | EstablishRemoteConnection | /CONN/${iot:ClientId} | The client populates the EstablishRemoteConnection Message with the required elements and publishes to the Connection topic. |
| 4. | Process Message | BIMD | The 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 Message | BIMD | EstablishAcknowledgement | ${iot:ClientId}/CONN | The service publishes the response message to the Connection topic for the client to receive. |
| 6. | Process Message | TBM/HU | The client receives the message and verifies the correlationId matches the messageId of the sent request. | ||
| 8. | Send EndConnection Message | TBM/HU | EndConnection | ${iot:ClientId}/CONN | The Client publishes the EndConnection message to stop the Connection to the Connection topic for the BIMD to receive. |
| 9. | Process Message | TBM/HU | The BIMD receives the message and verifies the correlationId matches the messageId of the initially sent request and stops the connection. |
This message is to establish Tunnel Connection from V2M.
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. |
This message is to Acknowledge the Connection Establishment.
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. |
| Name | Number | Description |
| SUCCESS | 0 | |
| FAILURE | 1 |
| Name | Number | Description |
| FAILED | 0 | |
| INVALID_PORT | 1 | |
| PORT_ALREADY_IN_USE | 2 | |
| INVALID_HOST | 3 | |
| INVALID_PRIORITY | 4 |
This message is to end the Tunnel Connection.
timestamp: 1488574019636
messageId: 1
messages
{
[com.fca.uconnect.global.endConnection]
{
connectionId: 123456
}
}
| Field | Type | Label | Description |
| connectionId | int32 | optional |
Here are some code samples to demonstrate how to create, send and receive messages. This tutorial shows how to
Start with .proto file. Add required messages and elements to each message.
Download Protobuf Compiler here and run the following command.
which then generates java file in package that you specified in .proto.
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:
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.
Change Log
| Version | Date | Notes |
|---|---|---|
| 1.1 | 2017-08-07 | Update KeepAlive |
| 1.0 | 2017-06-01 | Release of initial Proto |
| 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. |
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.
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.
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 |
Here are some code samples to demonstrate how to create, send and receive messages. This tutorial shows how to
Start with .proto file. Add required messages and elements to each message.
Download Protobuf Compiler here and run the following command.
which then generates java file in package that you specified in .proto.
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:
| .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 |