diff --git a/adapters/digital_twin/README.md b/adapters/digital_twin/README.md deleted file mode 100644 index 53478c3c..00000000 --- a/adapters/digital_twin/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Digital Twin Adapters - -A Digital Twin Adapter communicates with the In-Vehicle Digital Twin to get signal values during emission. - -A Digital Twin Adapter should implement the `DigitalTwinAdapter` trait from `freyja-common`. - -## General Behavior - -The sequence diagram below illustrates the general behavior of a Digital Twin Adapter after receiving a new mapping entry of a signal. - -Please see [the design document](../../docs/design/README.md) for how Freyja retrieves a new mapping entry. - -![digital_twin_adapter_sequence](../../docs/diagrams/digital_twin_adapter_sequence.svg). - -## Sample Digital Twin Adapters - -This directory contains sample implementations of the `DigitalTwinAdapter` trait from [contracts] diff --git a/docs/design/README.md b/docs/design/README.md index a975bf64..7bed66ef 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -30,7 +30,7 @@ The cartographer is the core component responsible for managing the digital twin The emitter is the core component responsible for actually emitting data. The emitter supports intervals at a per-signal level to enable signals to have different requirements on how often they are synced with the cloud. Note that once a signal is added to the mapping and picked up by the cartographer, it can take up to `min(`*`I`*`)` before the signal is emitted, where *`I`* is the set of intervals for signals already being tracked. -![Digital Twin Sequence Diagram](../diagrams/digital_twin_to_emitter_sequence.svg) +![Digital Twin Sequence Diagram](../diagrams/data_flow_to_emitter_sequence.svg) ### External Interfaces diff --git a/docs/diagrams/data_adapter_selection_sequence.puml b/docs/diagrams/data_adapter_selection_sequence.puml new file mode 100644 index 00000000..b24d96fb --- /dev/null +++ b/docs/diagrams/data_adapter_selection_sequence.puml @@ -0,0 +1,24 @@ +@startuml +participant "Freyja Cartographer" +participant "Data Adapter Selector" +participant "Data Adapter" +participant "In-Vehicle Digital Twin Provider" +autonumber + +== Selection of a Data Adapter == + +"Freyja Cartographer"->"Data Adapter Selector": create_or_update_adapter(entity) + +"Data Adapter Selector"->"Data Adapter Selector": Lookup adapter in selector's local cache + +alt #Aqua Matching Data Adapter Doesn't Exist + "Data Adapter Selector"->"Data Adapter": Create a data adapter associated with the entity endpoint +end + +"Data Adapter Selector"->"Data Adapter": Register the new entity +"Data Adapter Selector"->"Data Adapter Selector": Map entity to adapter in selector's local cache + +"Data Adapter" -> "In-Vehicle Digital Twin Provider": Call get or subscribe for values +"In-Vehicle Digital Twin Provider" -> "Data Adapter": Return values +== Selection of a Data Adapter == +@enduml \ No newline at end of file diff --git a/docs/diagrams/data_flow_to_emitter_sequence.puml b/docs/diagrams/data_flow_to_emitter_sequence.puml new file mode 100644 index 00000000..3cf9f9bf --- /dev/null +++ b/docs/diagrams/data_flow_to_emitter_sequence.puml @@ -0,0 +1,52 @@ +@startuml +participant "Cloud Digital Twin" +box Freyja +participant "Emitter" +participant "Signal Store" +participant "Cartographer" +participant "Digital Twin Adapter" +participant "Data Adapter Selector" +participant "Data Adapter" +end box +participant "Ibeji" +participant "Provider" + +autonumber + +== Data Flow to Emitter == + +"Cartographer"->"Digital Twin Adapter": Request DTDL for mapped entites +"Digital Twin Adapter"->"Ibeji": Send find_by_id request(s) +"Ibeji"->"Digital Twin Adapter": Respond with entity data +"Digital Twin Adapter"->"Cartographer": Respond with entity data +"Cartographer"->"Data Adapter Selector": Create or update data adapter with entity data +"Data Adapter Selector"->"Data Adapter Selector": Select correct Data Adapter +"Data Adapter Selector"->"Data Adapter": Register entity +alt Entity supports subscribe +"Data Adapter"->"Provider": Subscribe +"Data Adapter"<-"Provider": Subscribe Response +end +"Data Adapter"->"Data Adapter Selector": Register entity response +"Data Adapter Selector"->"Cartographer": Register entity response +"Cartographer"->"Signal Store": Track Signals +alt Entity doesn't support subscribe +"Emitter"->"Data Adapter Selector": Request signal value +"Data Adapter Selector"->"Data Adapter Selector": Select correct Data Adapter +"Data Adapter Selector"->"Data Adapter": Request signal value +"Data Adapter"->"Provider": Request signal value +"Data Adapter"<-"Provider": Signal value response +"Data Adapter Selector"<-"Data Adapter": Signal value response +"Emitter"<-"Data Adapter Selector": Signal value response +end +alt Entity supports subscribe +loop Provider publishes data asynchronously +"Provider"->"Data Adapter": Publish data +"Data Adapter"->"Signal Store": Update store +end +"Emitter"->"Signal Store": Request signal value +"Emitter"<-"Signal Store": Signal value response +end +"Emitter"->"Cloud Digital Twin": Emit signal data + +== Data Flow to Emitter == +@enduml diff --git a/docs/diagrams/digital_twin_adapter_sequence.puml b/docs/diagrams/digital_twin_adapter_sequence.puml deleted file mode 100644 index 333c8216..00000000 --- a/docs/diagrams/digital_twin_adapter_sequence.puml +++ /dev/null @@ -1,27 +0,0 @@ -@startuml -participant "Freyja" -participant "Digital Twin Adapter" -participant "In-Vehicle Digital Twin" -participant "Provider Proxy Selector" - - - - -autonumber - -== Received New Mapping Entry == - -"Freyja"->"Digital Twin Adapter": Get values for this signal - -alt #LightPink Metadata Required to Retrieve Signal Values - "Digital Twin Adapter"->"In-Vehicle Digital Twin": Requests additional info for signal - note left - Ex of Metadata: - Endpoint, supported operations, etc. - end note -end - -"Digital Twin Adapter"->"Provider Proxy Selector": CreateOrUpdateProviderProxy(entity_id, provider_uri, protocol, operation) - -== Received New Mapping Entry == -@enduml diff --git a/docs/diagrams/digital_twin_adapter_sequence.svg b/docs/diagrams/digital_twin_adapter_sequence.svg deleted file mode 100644 index b6c2c28a..00000000 --- a/docs/diagrams/digital_twin_adapter_sequence.svg +++ /dev/null @@ -1,40 +0,0 @@ -FreyjaFreyjaDigital Twin AdapterDigital Twin AdapterIn-Vehicle Digital TwinIn-Vehicle Digital TwinProvider Proxy SelectorProvider Proxy SelectorReceived New Mapping Entry1Get values for this signalalt[Metadata Required to Retrieve Signal Values]2Requests additional info for signalEx of Metadata:Endpoint, supported operations, etc.3CreateOrUpdateProviderProxy(entity_id, provider_uri, protocol, operation)Received New Mapping Entry \ No newline at end of file diff --git a/docs/diagrams/digital_twin_to_emitter_sequence.puml b/docs/diagrams/digital_twin_to_emitter_sequence.puml deleted file mode 100644 index de1d1c73..00000000 --- a/docs/diagrams/digital_twin_to_emitter_sequence.puml +++ /dev/null @@ -1,23 +0,0 @@ -@startuml -participant "Cloud Digital Twin" -participant "Freyja Cartographer" -participant "Freyja Emitter" -participant "DT Adapter" -participant "Ibeji" -participant "Provider" - -autonumber - -== Digital Twin Adapter Pushing Data to Emitter == - -"Freyja Cartographer"->"Freyja Emitter": Send mapping info -"Freyja Emitter"->"DT Adapter": Request DTDL for the specified providers -"DT Adapter"->"Ibeji": Send find_by_id request(s) -"Ibeji"->"DT Adapter": Respond with corresponding DTDL -"DT Adapter"->"Provider": Send get/subscribe request based on the DTDL -"Provider"->"DT Adapter": Send signal values asynchronously -"DT Adapter"->"Freyja Emitter": Update local provider value cache -"Freyja Emitter"->"Cloud Digital Twin": Emit signals - -== Digital Twin Adapter Pushing Data to Emitter == -@enduml diff --git a/docs/diagrams/digital_twin_to_emitter_sequence.svg b/docs/diagrams/digital_twin_to_emitter_sequence.svg deleted file mode 100644 index 4ba5972d..00000000 --- a/docs/diagrams/digital_twin_to_emitter_sequence.svg +++ /dev/null @@ -1,36 +0,0 @@ -Cloud Digital TwinCloud Digital TwinFreyja CartographerFreyja CartographerFreyja EmitterFreyja EmitterDT AdapterDT AdapterIbejiIbejiProviderProviderDigital Twin Adapter Pushing Data to Emitter1Send mapping info2Request DTDL for the specified providers3Send find_by_id request(s)4Respond with corresponding DTDL5Send get/subscribe request based on the DTDL6Send signal values asynchronously7Update local provider value cache8Emit signalsDigital Twin Adapter Pushing Data to Emitter \ No newline at end of file diff --git a/docs/diagrams/freyja_components.puml b/docs/diagrams/freyja_components.puml index 92935cd5..93a95635 100644 --- a/docs/diagrams/freyja_components.puml +++ b/docs/diagrams/freyja_components.puml @@ -1,14 +1,22 @@ @startuml +cloud { + [Mapping Service] as cloudMappingSvc +} + cloud { [Cloud Digital Twin] - [Mapping Service] } package "Vehicle" { frame "Freyja" { [Cartographer] [Emitter] + database "Signal Store" + [Data Adapter Selector] + node "Data Adapters" { + [Data Adapter] as data_adapter + } } [Chariott] @@ -21,15 +29,21 @@ package "Vehicle" { } [Cloud Connector] + [Mapping Service] as ivMappingSvc } -[Cartographer] <-l-> [Emitter] [Emitter] -u-> [Cloud Connector] : Emit Data -[Cartographer] <-u-> [Mapping Service] : Get Mapping +[Cartographer] <-[norank]-> [ivMappingSvc] : Get Mapping +[ivMappingSvc] <.u.> [cloudMappingSvc] [Cloud Connector] -u-> [Cloud Digital Twin] -[Emitter] .d.> [Chariott] : Discover Ibeji? -[Emitter] -d-> [ivdts] : Discover Providers -[Emitter] <-d-> [provider] : Collect Data via Get/Subscribe +[Cartographer] .d.> [Chariott] : Discover Ibeji (optional) +[Cartographer] -d-> [ivdts] : Discover Providers +[Cartographer] -u-> [Signal Store] : Track Signals +[Cartographer] -r-> [Data Adapter Selector] : Register Adapters +[Data Adapter Selector] -r-> [data_adapter] : Register Adapters +[data_adapter] <-d-> [provider] : Collect data +[data_adapter] -u-> [Signal Store] : Update signal values +[Emitter] <-l- [Signal Store] : Retrieve data [Chariott] <-r-> [ivdts] [ivdts] <-r-> [provider] diff --git a/docs/diagrams/mapping_service_to_cartographer_sequence.puml b/docs/diagrams/mapping_service_to_cartographer_sequence.puml index 5ba233d1..83d1174d 100644 --- a/docs/diagrams/mapping_service_to_cartographer_sequence.puml +++ b/docs/diagrams/mapping_service_to_cartographer_sequence.puml @@ -3,22 +3,16 @@ participant "Freyja Cartographer" participant "Mapping Service" autonumber -== Freyja Communication with Mapping Info Provider == - +== Freyja Communication with Mapping Service == "Freyja Cartographer"->"Mapping Service": Query for mapping metadata "Mapping Service"->"Freyja Cartographer": Respond with metadata -alt #LightPink Metadata specifies inventory update - "Freyja Cartographer"->"Mapping Service": Send requested inventory - "Mapping Service"->"Mapping Service": Record inventory and regenerate mapping -end - alt #LightBlue Metadata specifies a new mapping is available "Freyja Cartographer"->"Mapping Service": Query for mapping "Mapping Service"->"Freyja Cartographer" : Respond with mapping end -== Freyja Communication with Mapping Info Provider== +== Freyja Communication with Mapping Service == @enduml diff --git a/docs/diagrams/provider_proxy_selection_sequence.puml b/docs/diagrams/provider_proxy_selection_sequence.puml deleted file mode 100644 index b7eacfd6..00000000 --- a/docs/diagrams/provider_proxy_selection_sequence.puml +++ /dev/null @@ -1,25 +0,0 @@ -@startuml -participant "Digital Twin Adapter" -participant "Provider Proxy Selector" -participant "Provider Proxy" -participant "In-Vehicle Digital Twin Provider" -autonumber - -== Selection of a Provider Proxy == - -"Digital Twin Adapter"->"Provider Proxy Selector": CreateOrUpdateProviderProxy(entity_id, provider_uri, protocol, operation) - -alt #LightPink Provider Proxy Already Exist - "Provider Proxy Selector"->"Provider Proxy Selector": Add entity_id to provider proxy's local cache -end - -alt #Aqua Provider Proxy Doesn't Exist - "Provider Proxy Selector"->"Provider Proxy": Creates a provider proxy with provider uri and protocol - "Provider Proxy Selector"->"Provider Proxy": Start up - "Provider Proxy Selector"->"Provider Proxy Selector": Add entity_id to provider proxy's local cache -end - -"Provider Proxy" -> "In-Vehicle Digital Twin Provider": Call get or subscribe for values -"In-Vehicle Digital Twin Provider" -> "Provider Proxy": Return values -== Selection of a Provider Proxy == -@enduml \ No newline at end of file diff --git a/docs/diagrams/provider_proxy_selection_sequence.svg b/docs/diagrams/provider_proxy_selection_sequence.svg deleted file mode 100644 index 91cc4cce..00000000 --- a/docs/diagrams/provider_proxy_selection_sequence.svg +++ /dev/null @@ -1,38 +0,0 @@ -Digital Twin AdapterDigital Twin AdapterProvider Proxy SelectorProvider Proxy SelectorProvider ProxyProvider ProxyIn-Vehicle Digital Twin ProviderIn-Vehicle Digital Twin ProviderSelection of a Provider Proxy1CreateOrUpdateProviderProxy(entity_id, provider_uri, protocol, operation)alt[Provider Proxy Already Exist]2Add entity_id to provider proxy's local cachealt[Provider Proxy Doesn't Exist]3Creates a provider proxy with provider uri and protocol4Start up5Add entity_id to provider proxy's local cache6Call get or subscribe for values7Return valuesSelection of a Provider Proxy \ No newline at end of file