Skip to content

Protocol Documentation#

Table of Contents#

Top

ma/streaming/api/v1/api.proto#

AddAssociateSessionRequest#

Field Type Label Description
session_key string Unique session key of the parent session
associate_session_key string Unique session key of the associate session

AddAssociateSessionResponse#

Field Type Label Description
success bool Whether the add associate session request succeeded

CloseConnectionRequest#

Request to close an existing connection

Field Type Label Description
connection Connection Identifier for the connection

CloseConnectionResponse#

Response to a close connection request

Field Type Label Description
success bool Whether the close connection request succeeded

Connection#

A connection identifier

Field Type Label Description
id int64 For internal use only - do not modify this

ConnectionDetails#

Details of a connection

Field Type Label Description
data_source string Data source to read from
session string Session to read (can be ommitted if sessions are not being used)
streams string repeated Streams to read (can be ommitted if all streams are required)
stream_offsets int64 repeated Offset from which to start for each stream -1 = Latest, 0 = Earliest (default)
main_offset int64 Offset from which to start for the main data source topic
essentials_offset int64 Offset from which to start for the data source essentials topic

CreateSessionRequest#

Request for the creation of a new session

Field Type Label Description
data_source string Data Source name
type string Session type (defaults to "Session")
version uint32 Version (defaults to 1)

CreateSessionResponse#

Response to a session creation request

Field Type Label Description
session_key string Unique session key
new_session ma.streaming.open_data.v1.NewSessionPacket New session packet

DataPacketDetails#

Details for the packet being written

Field Type Label Description
message ma.streaming.open_data.v1.Packet Packet to write
data_source string Data source for this packet
stream string Stream name to which to write
session_key string Unique session key of the session to which to write

DataPacketRequest#

Request for reading parameters

Field Type Label Description
connection Connection Connection to Read
include_parameters string repeated Parameters to include (regular expressions)
exclude_parameters string repeated Parameters to exclude (regular expressions)
include_events string repeated Events to include (regular expressions)
exclude_events string repeated Events to exclude (regular expressions)
include_markers bool Include markers?

EndSessionRequest#

Request to end an existing session

Field Type Label Description
data_source string Data source name
session_key string Unique session key

EndSessionResponse#

Response to the termination of a session

Field Type Label Description
end_session ma.streaming.open_data.v1.EndOfSessionPacket End of session packet

GetConnectionRequest#

Request for details of an existing connection

Field Type Label Description
connection Connection Identifier for the connection

GetConnectionResponse#

Response to a get connection request

Field Type Label Description
details ConnectionDetails The connection details

GetCurrentSessionsRequest#

Request to return all sessions present on the broker for a given data source

Field Type Label Description
data_source string Data source name

GetCurrentSessionsResponse#

Response to the listing of all available sessions on the broker request

Field Type Label Description
session_keys string repeated List of unique session keys present on the broker for the specified data source

GetEventDataFormatIdRequest#

Request for a data format ID for a given event

Field Type Label Description
data_source string Data source for which this format is to be used
event string Event identifier

GetEventDataFormatIdResponse#

Response for a data format request

Field Type Label Description
data_format_identifier uint64 Data format identifier

GetEventRequest#

Request for an event from a data format ID

Field Type Label Description
data_source string Data source for which this format is used
data_format_identifier uint64 Data format identifier

GetEventResponse#

Response for an event request

Field Type Label Description
event string Event identifier

GetParameterDataFormatIdRequest#

Request for a data format ID for a given set of parameters

Field Type Label Description
data_source string Data source for which this format is to be used
parameters string repeated Ordered of parameter identifiers (the same parameters in a different order is a different id)

GetParameterDataFormatIdResponse#

Response for a data format request

Field Type Label Description
data_format_identifier uint64 Data format identifier

GetParametersListRequest#

Request for a list of parameters from a data format ID

Field Type Label Description
data_source string Data source for which this format is used
data_format_identifier uint64 Data format identifier

GetParametersListResponse#

Response for a parameter list request

Field Type Label Description
parameters string repeated List of parameters

GetSessionInfoRequest#

Request to return session info of a given session

Field Type Label Description
session_key string Unique session key

GetSessionInfoResponse#

Response to the session info request

Field Type Label Description
data_source string Data Source name
identifier string Identifier
type string Type
version uint32 Version
associate_session_keys string repeated Associate session keys
is_complete bool Shows whether the session is completed or not
streams string repeated Available streams
topic_partition_offsets GetSessionInfoResponse.TopicPartitionOffsetsEntry repeated The offsets into each topic / partition (key is topic name, optionally appended with a ':' followed by the partition number)
main_offset int64 Offset of the main data source topic
essentials_offset int64 Offset of the data source essentials topic

GetSessionInfoResponse.TopicPartitionOffsetsEntry#

Field Type Label Description
key string
value int64

GetSessionStartNotificationRequest#

Request for obtaining a session start notification

Field Type Label Description
data_source string Data source name

GetSessionStartNotificationResponse#

Response to a session start notification request

Field Type Label Description
session_key string Unique session key of the started session
data_source string Data source name

GetSessionStopNotificationRequest#

Request for obtaining a session end notification

Field Type Label Description
data_source string Data source name

GetSessionStopNotificationResponse#

Response to a session end notification request

Field Type Label Description
session_key string Unique session key of the ended session
data_source string Data source name

NewConnectionRequest#

Request for a new (read) connection

Field Type Label Description
details ConnectionDetails The connection details

NewConnectionResponse#

Response to a new connection request

Field Type Label Description
connection Connection Identifier for the connection

PacketResponse#

The return from a packet read

Field Type Label Description
packet ma.streaming.open_data.v1.Packet The packet that was read
stream string The stream the packet was read from

ReadDataPacketsRequest#

Field Type Label Description
request DataPacketRequest

ReadDataPacketsResponse#

Field Type Label Description
response PacketResponse repeated

ReadEssentialsRequest#

Field Type Label Description
connection Connection

ReadEssentialsResponse#

Field Type Label Description
response PacketResponse repeated

ReadPacketsRequest#

Field Type Label Description
connection Connection

ReadPacketsResponse#

Field Type Label Description
response PacketResponse repeated

UpdateSessionIdentifierRequest#

Field Type Label Description
session_key string Unique session key
identifier string Session identifier

UpdateSessionIdentifierResponse#

Field Type Label Description
success bool Whether the update session identifier request succeeded

WriteDataPacketRequest#

Request for writing a data packet to the stream

Field Type Label Description
detail DataPacketDetails

WriteDataPacketResponse#

Response to a request for writing a data packet to the stream

WriteDataPacketsRequest#

Request for writing a stream of data packets

Field Type Label Description
details DataPacketDetails repeated

WriteDataPacketsResponse#

Response to a request for writing a stream of data packets

WriteInfoPacketRequest#

Request for writing an info packet to the stream

Field Type Label Description
message ma.streaming.open_data.v1.Packet Packet to write
type InfoType Type for this packet

WriteInfoPacketResponse#

Response to a request for writing an info packet to the stream

WriteInfoPacketsRequest#

Request for writing a stream of info packets

Field Type Label Description
message ma.streaming.open_data.v1.Packet Packet to write
type InfoType Type for this packet

WriteInfoPacketsResponse#

Response to a request for writing a stream of info packets

InfoType#

Info type

Name Number Description
INFO_TYPE_UNSPECIFIED 0 Unspecified
INFO_TYPE_SESSION_INFO 1 Session info
INFO_TYPE_SYSTEM_STATUS 2 System status

ConnectionManagerService#

Connection manager service Open and close Connections Connections maintain the current offset position

Method Name Request Type Response Type Description
NewConnection NewConnectionRequest NewConnectionResponse Create a new connection
GetConnection GetConnectionRequest GetConnectionResponse Get an existing connection
CloseConnection CloseConnectionRequest CloseConnectionResponse Close connection

DataFormatManagerService#

Data format manager service

Method Name Request Type Response Type Description
GetParameterDataFormatId GetParameterDataFormatIdRequest GetParameterDataFormatIdResponse Request a data format ID for a set of parameters
GetEventDataFormatId GetEventDataFormatIdRequest GetEventDataFormatIdResponse Request a data format ID for an event
GetParametersList GetParametersListRequest GetParametersListResponse Request a list of paramters for a given data format ID
GetEvent GetEventRequest GetEventResponse Request an event for a given data format ID

PacketReaderService#

Read packets

Method Name Request Type Response Type Description
ReadPackets ReadPacketsRequest ReadPacketsResponse stream Continuously read all packets from the specified connection
ReadEssentials ReadEssentialsRequest ReadEssentialsResponse stream Continuously read all of the essential packets from this connection
ReadDataPackets ReadDataPacketsRequest ReadDataPacketsResponse stream Continuously read all data packets containing any of the specified parameters or events Only data packets will be returned (i.e. no config, metadata etc)

PacketWriterService#

Packet writer service.

Method Name Request Type Response Type Description
WriteDataPacket WriteDataPacketRequest WriteDataPacketResponse Write a packet for a specified data source
WriteDataPackets WriteDataPacketsRequest stream WriteDataPacketsResponse Continuously write a stream of data packets
WriteInfoPacket WriteInfoPacketRequest WriteInfoPacketResponse Write an info packet of a specified type
WriteInfoPackets WriteInfoPacketsRequest stream WriteInfoPacketsResponse Continuously write a stream of info packets

SessionManagementService#

Manage sessions

Method Name Request Type Response Type Description
CreateSession CreateSessionRequest CreateSessionResponse Create a new session. Returns the unique session key
EndSession EndSessionRequest EndSessionResponse End the session for a given unique session key
GetCurrentSessions GetCurrentSessionsRequest GetCurrentSessionsResponse Get a list of the current sessions within the broker
GetSessionInfo GetSessionInfoRequest GetSessionInfoResponse Get the info for a session
GetSessionStartNotification GetSessionStartNotificationRequest GetSessionStartNotificationResponse stream Continuously notifies the client when a session starts
GetSessionStopNotification GetSessionStopNotificationRequest GetSessionStopNotificationResponse stream Continuously notifies the client when a session ends
UpdateSessionIdentifier UpdateSessionIdentifierRequest UpdateSessionIdentifierResponse Update the session identifier given its unique session key
AddAssociateSession AddAssociateSessionRequest AddAssociateSessionResponse Add associate session to a session given its unique session key

Top

ma/streaming/open_data/v1/open_data.proto#

AxisDataPacket#

Values corresponsponding to points on an axis for map parameters

Field Type Label Description
axis_identifier string Axis identifier
timestamp fixed64 Timestamp
values ValueArray The data for the axis

BoolSample#

Field Type Label Description
value bool
status DataStatus

BoolSampleList#

Field Type Label Description
samples BoolSample repeated

ConfigurationPacket#

Data configuration

Field Type Label Description
config_id string Configuration ID
parameter_definitions ParameterDefinition repeated The parameter definitions
event_definitions EventDefinition repeated The event definitions
group_definitions GroupDefinition repeated The group definitions

DataFormatConfigurationPacket#

Data format

Field Type Label Description
data_format_id string Data format ID
data_formats DataFormatDefinitionPacket repeated The data format definitions

DataFormatDefinitionPacket#

Data Format Definition

Field Type Label Description
identifier uint64 Data format identifier
type DataFormatType Data format type
parameter_identifiers ParameterList
event_identifier string

DoubleSample#

Field Type Label Description
value double
status DataStatus

DoubleSampleList#

Field Type Label Description
samples DoubleSample repeated

EndOfSessionPacket#

A session has ended

Field Type Label Description
data_source string Data Source name
topic_partition_offsets EndOfSessionPacket.TopicPartitionOffsetsEntry repeated The offsets into each topic / partition (key is topic name, optionally appended with a ':' followed by the partition number)

EndOfSessionPacket.TopicPartitionOffsetsEntry#

Field Type Label Description
key string
value int64

EventDataFormat#

Desribes the event in this data packet

Field Type Label Description
data_format_identifier uint64
event_identifier string

EventDefinition#

Defines the metadata for a given event

Field Type Label Description
identifier string The full identifier for the event
name string The name of the event
definition_id uint32 A numeric identifier for the event
application_name string The application containing the event
description string The event description
priority EventPriority Event priority
groups string repeated List of group identifiers in which the event should appear
data_types DataType repeated List of native data types for each value
format_strings string repeated List of format strings, applied to event values for display
conversions TextConversionDefinition repeated Text conversion rules to be applied to event values if applicable

EventPacket#

Event

Field Type Label Description
data_format EventDataFormat Data format
timestamp fixed64 Time the event occurred
raw_values double repeated Raw data (list of doubles, event specific meaning)

FormulaDefinition#

A formula definition

Field Type Label Description
type FormulaType Type of formula
formula string The formula code

GroupDefinition#

Defines the group

Field Type Label Description
identifier string The full identifier for the group
name string The name of the group
application_name string The applicaion that the group is contained within
description string Description for the group
groups GroupDefinition repeated Any subgroups nested within the group

Int32Sample#

Field Type Label Description
value int32
status DataStatus

Int32SampleList#

Field Type Label Description
samples Int32Sample repeated

MapDataPacket#

Values corresponsponding to the map

Field Type Label Description
map_identifier string Map identifier
timestamp fixed64 Timestamp
x_axis_identifier string The identifier of the X axis
x_index_identifier string The identifier of the X axis index parameter
y_axis_identifier string The name of the Y axis (only for 2D maps)
y_index_identifier string The identifier of the Y axis index parameter (only for 2D maps)
values ValueArray repeated The data for the map

MarkerPacket#

Marker

Field Type Label Description
timestamp fixed64 Start time of marker
end_time fixed64 End time of marker (optional)
label string Text label
type string Type of marker
description string Text Description
source string Source
value int64 Value of the marker if applicable

MetadataPacket#

General metadata

Field Type Label Description
metadata MetadataPacket.MetadataEntry repeated Metadata

MetadataPacket.MetadataEntry#

Field Type Label Description
key string
value google.protobuf.Any

NewSessionPacket#

New session has started

Field Type Label Description
data_source string Data Source name
topic_partition_offsets NewSessionPacket.TopicPartitionOffsetsEntry repeated The offsets into each topic / partition (key is topic name, optionally appended with a ':' followed by the partition number)

NewSessionPacket.TopicPartitionOffsetsEntry#

Field Type Label Description
key string
value int64

Packet#

Wrapper for all packets

Field Type Label Description
type string Message type (unique name)
session_key string Unique session key
is_essential bool Is this packet essential?
content bytes Content

ParameterDefinition#

Defines the metadata for a given parameter

Field Type Label Description
identifier string The full identifier for the parameter
name string The name of the parameter
application_name string The application containing the parameter
description string The parameter description
groups string repeated List of group identifiers in which the parameter should appear
units string Units that this parameter is measured in
data_type DataType Native data type
format_string string Format strings, applied to sample values for display
min_value double Minimum value expected for samples of this parameter
max_value double Maximum value expected for samples of this parameter
warning_min_value double Threshold minimum value for warnings
warning_max_value double Threshold maximum value for warnings
frequencies double repeated Frequencies at which samples of this parameter may be sent
includes_row_data bool Whether row data samples may be sent for this parameter
includes_synchro_data bool Whether synchro data samples may be sent for this parameter
conversion TextConversionDefinition Text conversion rule to be applied if applicable
formula FormulaDefinition Formula for calculating sample values if applicable

ParameterList#

List of parameter identifiers

Field Type Label Description
parameter_identifiers string repeated

PeriodicDataPacket#

Telemetry samples in periodic format (equally spaced / fixed frequency samples)

Field Type Label Description
data_format SampleDataFormat Data format
start_time fixed64 Start time (timestamp of first sample)
interval uint32 Step / time between samples
columns SampleColumn repeated The rest of the Data Each column must have the same no of values

RawCANDataPacket#

Raw CAN message

Field Type Label Description
timestamp fixed64 Timestamp of the packet
bus uint32 CAN Bus
can_id uint32 CAN ID
payload bytes Message payload

RowDataPacket#

Telemetry samples in time series format (timestamped rows)

Field Type Label Description
data_format SampleDataFormat Data format
timestamps fixed64 repeated Timestamps
rows SampleRow repeated The rest of the Data Each row must have the same no of values = the same as the parameters

SampleColumn#

"Column" of telemetry sample values

Field Type Label Description
double_samples DoubleSampleList
int32_samples Int32SampleList
bool_samples BoolSampleList
string_samples StringSampleList

SampleDataFormat#

Desribes the parameters in this data packet

Field Type Label Description
data_format_identifier uint64
parameter_identifiers ParameterList

SampleRow#

"Row" of telemetry sample values

Field Type Label Description
double_samples DoubleSampleList
int32_samples Int32SampleList
bool_samples BoolSampleList
string_samples StringSampleList

SessionInfoPacket#

Session info

Field Type Label Description
data_source string Data Source name
identifier string Identifier
type string Type
version uint32 Version
associate_session_keys string repeated Associate session keys

StringSample#

Field Type Label Description
value string
status DataStatus

StringSampleList#

Field Type Label Description
samples StringSample repeated

SynchroDataPacket#

Telemetry samples in synchro format (variable frequency samples)

Field Type Label Description
data_format SampleDataFormat Data format
start_time fixed64 Start time (timestamp of first sample)
intervals uint32 repeated Step / time between each sample and the previous
column SampleColumn repeated The rest of the Data Each column must have number of values = number of intervals + 1

SystemStatusMessage#

A system status message

Field Type Label Description
service string Service to which this message relates
data_source string Data source name that this service relates to
type SystemStatusType Type of message

Contents......... TBD |

TextConversionDefinition#

A text conversion definition

Field Type Label Description
conversion_identifier string The conversion rule identifier
input_values double repeated The values to convert from
string_values string repeated The strings to convert to
default string The default string if the input does not match

ValueArray#

"Array" of values

Field Type Label Description
values double repeated

DataFormatType#

Data format type

Name Number Description
DATA_FORMAT_TYPE_UNSPECIFIED 0
DATA_FORMAT_TYPE_PARAMETER 1
DATA_FORMAT_TYPE_EVENT 2

DataStatus#

Data status showing if samples are invalid for any reason

Name Number Description
DATA_STATUS_UNSPECIFIED 0
DATA_STATUS_VALID 1
DATA_STATUS_MISSING 2
DATA_STATUS_ERROR 3

DataType#

Native data type

Name Number Description
DATA_TYPE_UNSPECIFIED 0 Unspecified
DATA_TYPE_FLOAT64 1 64 bit floating point (i.e. “double”)
DATA_TYPE_FLOAT32 2 32 bit floating point
DATA_TYPE_UINT32 3 32 bit unsigned integer
DATA_TYPE_SINT32 4 32 bit signed integer
DATA_TYPE_UINT16 5 16 bit unsigned integer
DATA_TYPE_SINT16 6 16 bit signed integer
DATA_TYPE_UINT8 7 8 bit unsigned integer
DATA_TYPE_SINT8 8 8 bit signed integer
DATA_TYPE_STRING 9 String

EventPriority#

Event priority type

Name Number Description
EVENT_PRIORITY_UNSPECIFIED 0
EVENT_PRIORITY_CRITICAL 1
EVENT_PRIORITY_HIGH 2
EVENT_PRIORITY_MEDIUM 3
EVENT_PRIORITY_LOW 4
EVENT_PRIORITY_DEBUG 5

FormulaType#

Types of formula. Can be extended to support other languages in the future

Name Number Description
FORMULA_TYPE_UNSPECIFIED 0 Unspecified
FORMULA_TYPE_FDL 1 Mclaren Applied proprietary FDL, used for virtual parameters

SystemStatusType#

Types of status message

Name Number Description
SYSTEM_STATUS_TYPE_UNSPECIFIED 0 Unspecified
SYSTEM_STATUS_TYPE_HEARTBEAT 1 Service is still alive
SYSTEM_STATUS_TYPE_STATUS 2 Service has a status update
SYSTEM_STATUS_TYPE_ERROR 3 Service has generated an error
SYSTEM_STATUS_TYPE_WARNING 4 Service has generated a warning
SYSTEM_STATUS_TYPE_CONNECTION 5 A source has connected/disconnected

Top

ma/streaming/key_generator/v1/key_generator.proto#

GenerateUniqueKeyRequest#

Request for generating a unique key

Field Type Label Description
type KeyType

GenerateUniqueKeyResponse#

Response to a request for generating a unique key

Field Type Label Description
string_key string
ulong_key uint64

KeyType#

The type of key that should be generated

Name Number Description
KEY_TYPE_UNSPECIFIED 0
KEY_TYPE_ULONG 1
KEY_TYPE_STRING 2

UniqueKeyGeneratorService#

Unique key generator service

Method Name Request Type Response Type Description
GenerateUniqueKey GenerateUniqueKeyRequest GenerateUniqueKeyResponse Generate a unique key which can be used to uniquely identify entities

Scalar Value Types#

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 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 int32 int integer Bignum or Fixnum (as required)
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 int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)