diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/main/doc/images/ClientLocationServices.png | bin | 0 -> 242057 bytes | |||
| -rw-r--r-- | src/main/doc/images/General MQTT Message Lifecycle.png | bin | 0 -> 98436 bytes | |||
| -rw-r--r-- | src/main/doc/images/mqttLocation.png | bin | 0 -> 242069 bytes | |||
| -rw-r--r-- | src/main/doc/puml/IntelligentDataCollection.puml | 87 | ||||
| -rw-r--r-- | src/main/doc/puml/mqtt_client_Location_Services.puml | 106 | ||||
| -rw-r--r-- | src/main/doc/puml/mqtt_client_message_life_cycle.puml | 2 | ||||
| -rw-r--r-- | src/main/proto/.DS_Store | bin | 6148 -> 8196 bytes | |||
| -rw-r--r-- | src/main/proto/messages/.DS_Store | bin | 0 -> 6148 bytes | |||
| -rw-r--r-- | src/main/proto/messages/VehicleMessageHeader.proto | 54 | ||||
| -rw-r--r-- | src/main/proto/messages/VehiclePrecisionLocation.proto | 83 | ||||
| -rw-r--r-- | src/main/proto/messages/VehicleRemoteHvac.proto | 103 |
11 files changed, 338 insertions, 97 deletions
diff --git a/src/main/doc/images/ClientLocationServices.png b/src/main/doc/images/ClientLocationServices.png Binary files differnew file mode 100644 index 0000000..741da08 --- /dev/null +++ b/src/main/doc/images/ClientLocationServices.png diff --git a/src/main/doc/images/General MQTT Message Lifecycle.png b/src/main/doc/images/General MQTT Message Lifecycle.png Binary files differnew file mode 100644 index 0000000..442b202 --- /dev/null +++ b/src/main/doc/images/General MQTT Message Lifecycle.png diff --git a/src/main/doc/images/mqttLocation.png b/src/main/doc/images/mqttLocation.png Binary files differnew file mode 100644 index 0000000..cc54870 --- /dev/null +++ b/src/main/doc/images/mqttLocation.png diff --git a/src/main/doc/puml/IntelligentDataCollection.puml b/src/main/doc/puml/IntelligentDataCollection.puml index ac2c2d3..3a7b988 100644 --- a/src/main/doc/puml/IntelligentDataCollection.puml +++ b/src/main/doc/puml/IntelligentDataCollection.puml @@ -1,11 +1,84 @@ -@startuml -'https://plantuml.com/sequence-diagram -autonumber +@startuml "Intelligent Data Collection" +participant "Vehicle Telematics Module" as VTM +participant "Broker" as iot +database "Telemetry Data" as TDB +participant "Vehicle Status" as vehstat +database "Vehicle Model and Mapping" as VMDB +participant "Intelligent Data Service" as IDS +participant "Analytics Services" as AS +participant "Consuming Services" as CS +actor "Developer/Engineer" as DE +participant "Consuming Application" + + +DE -> IDS: Model Vehicle Data +IDS -> VMDB: Store Vehicle Models +DE -> IDS: Map Model to Vehicle Data Schemas (i.e. DBC) +IDS -> VMDB: Store Vehicle Model and Mapping +=== Load Vehicle Model Mapping == +IDS -> iot: Publish message PublishVehicleModelMapping +alt Vehicle Connected +iot -> VTM: Receive PublishVehicleModelMapping +note right of VTM: The vehicle uses the mapping to abstract and transform vehicle network data to the Model. +else else Vehicle Not Connected +vehstat -> IDS: isVehicleSubscribedResponse (Not Subscribed) + +create boundary "SMS/Cellular Services" as sms +IDS -> sms: Send SMS Wake up Message +VTM -> iot: Connect +iot -> iot: Authorization check +iot -> VTM: ConnectAck +iot -> vehstat: <VTM_id> Connected +vehstat -> IDS: <VTM_id> Connected +IDS -> iot: Subscribe to <response_topic_id> +iot -> IDS: SUBACK +IDS -> iot: Publish PublishVehicleModelMapping +end +iot -> VTM: Receive PublishVehicleModelMapping +iot -> IDS: PUBACK + + +== Send Vehicle Data Collection Scheme == +DE -> IDS: Design Data Collection Scheme +note right of IDS: These services permit identifying just the data needed\n for a specific use case and the collection intervals\n either by event or time based. +alt Vehicle Connected +iot -> VTM: Receive PublishDataCollectionDescriptor +note right of VTM: The vehicle uses the mapping to abstract and transform vehicle network data to the Model. +else else Vehicle Not Connected +vehstat -> IDS: isVehicleSubscribedResponse (Not Subscribed) + +create boundary "SMS/Cellular Services" as sms +IDS -> sms: Send SMS Wake up Message +VTM -> iot: Connect +iot -> iot: Authorization check +iot -> VTM: ConnectAck +iot -> vehstat: <VTM_id> Connected +vehstat -> IDS: <VTM_id> Connected +IDS -> iot: Subscribe to <response_topic_id> +iot -> IDS: SUBACK +IDS -> iot: Publish PublishDataCollectionDescriptor +end +iot -> VTM: Receive PublishDataCollectionDescriptor +iot -> IDS: PUBACK + +== Publish Data From Vehicle == + +loop Publish as Per Collection Scheme +VTM <-: Event or Interval +VTM -> iot: Connect +VTM -> iot: PublishData +iot -> iot: Authorization check +iot -> VTM: ConnectAck +iot -> vehstat: <VTM_id> Connected +vehstat -> IDS: <VTM_id> Connected +VTM -> iot: PublishData +iot -> IDS: Receive PublishData +IDS -> TD: Store Data +AS -> TD: Retrieve and Transform Data +AS -> CS: Consume Data for Business Purposes +end + -Alice -> Bob: Authentication Request -Bob --> Alice: Authentication Response -Alice -> Bob: Another authentication Request -Alice <-- Bob: another authentication Response @enduml
\ No newline at end of file diff --git a/src/main/doc/puml/mqtt_client_Location_Services.puml b/src/main/doc/puml/mqtt_client_Location_Services.puml new file mode 100644 index 0000000..48f2e64 --- /dev/null +++ b/src/main/doc/puml/mqtt_client_Location_Services.puml @@ -0,0 +1,106 @@ +@startuml "mqtt Location Services Orchestration" + + +participant "Vehicle Application" as application +participant "Vehicle Edge MQTT Client" as client +participant "MQTT Broker" as broker +participant "Vehicle Location Service" as vehsloc +participant "Location Enrichment Service" as cvc +boundary "Outgoing Event Service" as pub +database "Vehicle State" as vstat +note left of application: This flow assumes \n the previous security \nlifecycle has been\n completed and TLS TCP \n connection established + + +== Vehicle Event Publishing === +client -> broker: Connect +broker -> broker: Authorization check +broker -> client: ConnectAck +broker -> vehsloc: <client_id> Connected +application -> broker: Publish <topic_id> +broker -> application: PUBACK +broker -> vehsloc: <client_id> Published CurrentLocationMessage +vehsloc -> cvc: <i>EnrichLocationData<i> +cvc -> vehsloc: <i>Response> +note right of cvc: Use to add more details such as address or points of interest +vehsloc -> pub: Publish event to consuming applications via API +vehsloc -> vstat: Store current location state + +== Request and Response == +pub -> vstat: Current Location +create actor "Consuming Application User" as user +pub -> user: Current location +create participant "APIs" as api +user -> api: Request Location Update +api -> vehsloc: RequestCurrentVehicleLocation + +pub -> vehsloc: Message/Request for Vehicle +vehsloc -> vehsloc: Create Message +vehsloc -> vehstat: isVehicleSubscribed to <topic_id> +alt Vehicle Connected and Subscribed +vehstat -> vehsloc: isVehicleSubscribedResponse (Subscribed) +note right of vehstat: The response should indicate both connection and subscription status for appropriate action to be taken +vehsloc -> broker: Subscribe to <response_topic_id> +broker -> vehsloc: SUBACK +vehsloc -> broker: Publish to <topic_id> +broker -> vehsloc: PUBACK + + + +else else "Client Not Connected/Subscribed" +vehstat -> vehsloc: isVehicleSubscribedResponse (Not Subscribed) + +create boundary "SMS/Cellular Services" as sms +vehsloc -> sms: Send SMS Wake up Message +client -> broker: Connect +broker -> broker: Authorization check +broker -> client: ConnectAck +broker -> vehstat: <client_id> Connected +vehstat -> vehsloc: <client_id> Connected +vehsloc -> broker: Subscribe to <response_topic_id> +broker -> vehsloc: SUBACK +vehsloc -> broker: Publish to <topic_id> +broker -> vehsloc: PUBACK + +end + +broker <-> application: message received +application -> broker: ACK (QoS dependent) +application -> application: deserialize and take action +application -> application: create response message +application -> broker: Pubish Response to <response_topic_id> +broker -> vehsloc: Response Message +vehsloc -> pub: Response Message +vehsloc -> broker: Subscribe to <response_topic_id> +broker -> vehsloc: SUBACK +vehsloc -> broker: Publish to <topic_id> +broker -> vehsloc: PUBACK +broker <-> application: message received +application -> broker: ACK (QoS dependent) +application -> application: deserialize and take action +application -> application: create response message +application -> broker: Pubish Response to <response_topic_id> +broker -> vehsloc: Response Message +vehsloc -> pub: Response Message +vehsloc -> vehstat: Update Location +pub -> user: New Location Data + +alt "Vehicle Connected" +vehsloc -> broker: Publish RequestCurrentVehicleLocation +else else "Vehicle not Connected" +vehsloc -> client: (SMS) Wake up sent +client -> broker: Connect +broker -> broker: Authorization check +broker -> client: ConnectAck +end + + + + + + + + + + + +@enduml
\ No newline at end of file diff --git a/src/main/doc/puml/mqtt_client_message_life_cycle.puml b/src/main/doc/puml/mqtt_client_message_life_cycle.puml index 247b34c..23232a4 100644 --- a/src/main/doc/puml/mqtt_client_message_life_cycle.puml +++ b/src/main/doc/puml/mqtt_client_message_life_cycle.puml @@ -1,4 +1,4 @@ -@startuml "Lifecycle" +@startuml "General MQTT Message Lifecycle" participant "Vehicle Application" as application diff --git a/src/main/proto/.DS_Store b/src/main/proto/.DS_Store Binary files differindex 49a1204..7d17bb7 100644 --- a/src/main/proto/.DS_Store +++ b/src/main/proto/.DS_Store diff --git a/src/main/proto/messages/.DS_Store b/src/main/proto/messages/.DS_Store Binary files differnew file mode 100644 index 0000000..5008ddf --- /dev/null +++ b/src/main/proto/messages/.DS_Store diff --git a/src/main/proto/messages/VehicleMessageHeader.proto b/src/main/proto/messages/VehicleMessageHeader.proto index 5da44a9..2a6cda0 100644 --- a/src/main/proto/messages/VehicleMessageHeader.proto +++ b/src/main/proto/messages/VehicleMessageHeader.proto @@ -1,30 +1,40 @@ -syntax = "proto3"; -import "vss/vspec.proto"; -package messages; - +syntax = "proto3";/** +*<h1>Vehicle Message Header</h1> +*<p> +* This message defines an application message header for messages past across the system. This is useful because the standard MQTT message headers are typically local to the broker of the system, so while the MQTT headers are useful for QoS assurances and message debugging they do not necessarily correlate the messages to the services deeper in the vehicle or the cloud services. +*</p> +*<h2>Message Orchestration</h2> +*<p><img src="doc/images/VehicleMessageHeader.png" alt="HeaderMessage.puml"></p> +*<h2>MQTT Topic Design</h2> +*<table> +* <thead> +* <tr> +* <th>Direction</th> +* <th>Subscribe Topic</th> +* <th>Publish Topic</th> +* </tr> +* </thead> +* <tbody> +* <tr> +* <td>Vehicle to Cloud</td> +* <td>No Topic</td> +* <td>No Topic</td> +* </tr> +* <tr> +* <td>Cloud to Vehicle</td> +* <td>No Topic</td> +* <td>No Topic</td> +* </tr> +* </tbody> +* </table> +*/ -// # Vehicle Message Header -// -// This message defines an application message header for messages past across the system. This is useful because the standard MQTT message headers are typically local to the broker of the system, so while the MQTT headers -// are useful for QoS assurances and message debugging they do not necessarily correlate the messages to the -// services deeper in the vehicle or the cloud services. -// -// ## Message Orchestration -//  -// -// ## MQTT Topic Design -// | Direction | Subscribe Topic | Publish Topic | -// | ----------- | ----- | -------- | -// | Vehicle to Cloud | No Topic | No Topic | -// | ----------- | ----- | -------- | -// | Cloud to Vehicle | No Topic | No Topic | -// -// +package messages; message VehicleMessageHeading { int32 message_id = 1; // Unique Application message_id. When initiated from channels like Mobile or API Gateways this should persist all the way to the vehilce, returning as a correlation id. int32 correlation_id = 2; // For request/response and other multi-message patterns this should be populated with the message_id of the first message in the chain. -.vss.VehicleVehicleIdentification vehicle_identity = 3; // this should be salted and hashed version of the VIN or other Vehicle Identification. +string vehicle_identity = 3; // this should be salted and hashed version of the VIN or other Vehicle Identification. string vehicle_device_id = 7; // this can be any unique identifier for the vehicle, we recommend using the fingerprint on the client's unique x.509 certificate. int64 message_timestamp = 4; // EPOCH timestamp when the message was created double protocol_version = 5; // version of the protocol schema/data model being used. diff --git a/src/main/proto/messages/VehiclePrecisionLocation.proto b/src/main/proto/messages/VehiclePrecisionLocation.proto index 4438c79..7e132ec 100644 --- a/src/main/proto/messages/VehiclePrecisionLocation.proto +++ b/src/main/proto/messages/VehiclePrecisionLocation.proto @@ -1,39 +1,46 @@ -syntax = "proto3"; +syntax = "proto3"; /** +* <h1>Precise Vehicle Location</h1> +*<p>This set of messages define how to acquire vehicle location, either on demand or by interval and events.</p> +*<h2>Message Orchestration</h2> +*<p><img src="doc/images/mqttLocation.png" alt="HeaderMessage.puml"></p> +*<h2>MQTT Topic Design</h2> +*<table> +* <thead> +* <tr> +* <th>Direction</th> +* <th>Subscribe Topic</th> +* <th>Publish Topic</th> +* </tr> +* </thead> +* <tbody> +* <tr> +* <td>Vehicle to Cloud</td> +* <td>vloc/"*"</td> +* <td>vloc/<device_id></td> +* </tr> +* <tr> +* <td>Cloud to Vehicle</td> +* <td><device_id>/vloc</td> +* <td><device_id>/vloc</td> +* </tr> +* </tbody> +* </table> +*/ -package messages.location; -import "vss/vspec.proto"; +package messages; import "messages/VehicleMessageHeader.proto"; - - -// # Precise Vehicle Location -// -// This set of messages define how to aquire vehicle location, either on demand or by interval and events. -// -// ## Message Orchestration -// [TO-DO] -// -// ## MQTT Topic Design -// | Direction | Subscribe Topic | Publish Topic | -// | ----------- | ----- | -------- | -// | Vehicle to Cloud | vloc/* | vloc/<device_id> | -// | ----------- | ----- | -------- | -// | Cloud to Vehicle | <device_id>/vloc| <device_id>/vloc | -// -// - - -message RequestCurrentVehicleLocation +message RequestCurrentVehicleLocationTest /// Requests vehicle location on demand { - .vss.VehicleVehicleIdentification vehicleIdentification = 1; /// At most this identity should be all that is required to trigger the request for location + string vehicle_identity = 1; /// At most this identity should be all that is required to trigger the request for location and should contain a salted hash } message ResponseCurrentVehicleLocation /// Response to vehicle location request { - .messages.VehicleMessageHeading vehicleMessageHeading =1; - .vss.VehicleCurrentLocation vehicleCurrentLocation =2; + VehicleMessageHeading vehicleMessageHeading =1; + VehicleCurrentLocation vehicleCurrentLocation =2; ResponseStatusEnum responseStatus = 3; } @@ -46,8 +53,30 @@ enum ResponseStatusEnum { message PublishCurrentVehicleLocation /// This is the event based version, proactively publishing location data without a cloud side request { VehicleMessageHeading vehicleMessageHeading =1; - .vss.VehicleCurrentLocation vehicleCurrentLocation =2; + VehicleCurrentLocation vehicleCurrentLocation =2; } +message VehicleCurrentLocation { + string Timestamp = 1; + double Latitude = 2; + double Longitude = 3; + double Heading = 4; + double HorizontalAccuracy = 5; + double Altitude = 6; + double VerticalAccuracy = 7; + + VehicleCurrentLocationGNSSReceiver GNSSReceiver = 8; +} + +message VehicleCurrentLocationGNSSReceiver { + string FixType = 1; + VehicleCurrentLocationGNSSReceiverMountingPosition MountingPosition = 2; +} + +message VehicleCurrentLocationGNSSReceiverMountingPosition { + int32 X = 1; + int32 Y = 2; + int32 Z = 3; +} diff --git a/src/main/proto/messages/VehicleRemoteHvac.proto b/src/main/proto/messages/VehicleRemoteHvac.proto index 2ccc4af..38afaae 100644 --- a/src/main/proto/messages/VehicleRemoteHvac.proto +++ b/src/main/proto/messages/VehicleRemoteHvac.proto @@ -1,41 +1,48 @@ -syntax = "proto3"; -/** # Cabin Preconditioning -This set of messages define how to aquire vehicle location, either on demand or by interval and events. - ## Message Orchestration - [TO-DO] - ## MQTT Topic Design - | Direction | Subscribe Topic | Publish Topic | - | ----------- | ----- | -------- | - | Vehicle to Cloud | cabin/# |cabin/<device_id> | - | ----------- | ----- | -------- | - | Cloud to Vehicle | <device_id>/cabin| <device_id>/cabin | - **/ +syntax = "proto3"; /** +* <h2>Cabin Preconditioning</h2> +* <p>This set of messages define how to acquire vehicle location, either on demand or by interval and events.</p> +* +* <h3>Message Orchestration</h3> +* <p>[TO-DO]</p> +* +* <h3>MQTT Topic Design</h3> +* <table> +* <thead> +* <tr> +* <th>Direction</th> +* <th>Subscribe Topic</th> +* <th>Publish Topic</th> +* </tr> +* </thead> +* <tbody> +* <tr> +* <td>Vehicle to Cloud</td> +* <td>cabin/#</td> +* <td>cabin/<device_id></td> +* </tr> +* <tr> +* <td>Cloud to Vehicle</td> +* <td><device_id>/cabin</td> +* <td><device_id>/cabin</td> +* </tr> +* </tbody> +* </table> +*/ import "google/protobuf/timestamp.proto"; -package messages.hvac; - -message Temperature { - float value = 1; // Temperature value - string unit = 2; // Temperature unit (e.g., "Celsius", "Fahrenheit") -} +package messages; +message CabinConditionStatusPublish { -message HVACZone { - enum Zone { - DRIVER = 0; - PASSENGER = 1; - REAR_LEFT = 2; - REAR_RIGHT = 3; - } - - Zone zone = 1; // HVAC Zone - Temperature target_temperature = 2; // Target temperature + google.protobuf.Timestamp event_time = 1; // Time of the event + HVACState hvac_state = 2; // Current state of the HVAC + CabinTemperature cabin_temperature = 3; // Current cabin temperature } message PreconditionRequest { - + repeated HVACZone hvac_zones = 1; // List of HVAC zones to precondition // For scheduled preconditioning, set the start_time to the desired future time. // For on-demand preconditioning, leave the start_time unset. - google.protobuf.Timestamp start_time = 2; + google.protobuf.Timestamp start_time = 2; } message PreconditionResponse { @@ -44,11 +51,35 @@ message PreconditionResponse { FAILURE = 1; PENDING = 2; } - + Status status = 1; // Status of the precondition request string message = 2; // Optional message } +message CabinTemperature { + Temperature temperature = 1; // Current cabin temperature + HVACZone zone = 2; // Zone of the reported temperature +} + + +message Temperature { + float value = 1; // Temperature value + string unit = 2; // Temperature unit (e.g., "Celsius", "Fahrenheit") +} + +message HVACZone { + enum Zone { + DRIVER = 0; + PASSENGER = 1; + REAR_LEFT = 2; + REAR_RIGHT = 3; + } + + Zone zone = 1; // HVAC Zone + Temperature target_temperature = 2; // Target temperature +} + + message HVACState { enum State { OFF = 0; @@ -61,13 +92,5 @@ message HVACState { HVACZone current_zone = 2; // Current active zone } -message CabinTemperature { - Temperature temperature = 1; // Current cabin temperature - HVACZone zone = 2; // Zone of the reported temperature -} -message CabinConditionStatusPublish { - google.protobuf.Timestamp event_time = 1; // Time of the event - HVACState hvac_state = 2; // Current state of the HVAC - CabinTemperature cabin_temperature = 3; // Current cabin temperature -}
\ No newline at end of file + |
