From 13d25d56fc6b3eab312ef4089ef4270c18eb819d Mon Sep 17 00:00:00 2001 From: William Lyles <26171886+wilyle@users.noreply.github.com> Date: Thu, 25 Jan 2024 15:22:39 -0800 Subject: [PATCH] Update documentation (#119) Updates documentation to reflect the latest state of Freyja Fixes #112 --- .accepted_words.txt | 4 + README.md | 4 +- adapters/data/grpc_data_adapter/README.md | 2 +- .../data/http_mock_data_adapter/README.md | 2 +- .../in_memory_mock_data_adapter/README.md | 2 +- .../managed_subscribe_data_adapter/README.md | 2 +- adapters/data/mqtt_data_adapter/README.md | 2 +- .../README.md | 2 +- .../mock_digital_twin_adapter/README.md | 2 +- .../in_memory_mock_mapping_adapter/README.md | 2 +- .../mock_mapping_service_adapter/README.md | 2 +- docs/design/README.md | 80 +++++++++---- .../azure_digital_twins_cloud_connector.puml | 0 .../azure_digital_twins_cloud_connector.svg | 0 .../diagrams/azure_mqtt_cloud_connector.puml | 0 .../diagrams/azure_mqtt_cloud_connector.svg | 0 .../data_adapter_selection_sequence.puml | 12 +- .../data_adapter_selection_sequence.svg | 47 ++++++++ .../diagrams/data_flow_sequence.puml} | 8 +- docs/design/diagrams/data_flow_sequence.svg | 69 ++++++++++++ .../diagrams/freyja_components.puml | 14 ++- docs/design/diagrams/freyja_components.svg | 106 ++++++++++++++++++ ...ping_service_to_cartographer_sequence.puml | 0 ...pping_service_to_cartographer_sequence.svg | 0 .../data_adapter_selection_sequence.svg | 37 ------ .../data_flow_to_emitter_sequence.svg | 65 ----------- docs/diagrams/freyja_components.svg | 94 ---------------- docs/quickstart.md | 81 ------------- docs/{ => tutorials}/config-overrides.md | 4 +- docs/{ => tutorials}/custom-adapters.md | 12 +- docs/tutorials/quickstart.md | 73 ++++++++++++ mocks/mock_digital_twin/README.md | 2 +- 32 files changed, 408 insertions(+), 322 deletions(-) rename docs/{ => design}/diagrams/azure_digital_twins_cloud_connector.puml (100%) rename docs/{ => design}/diagrams/azure_digital_twins_cloud_connector.svg (100%) rename docs/{ => design}/diagrams/azure_mqtt_cloud_connector.puml (100%) rename docs/{ => design}/diagrams/azure_mqtt_cloud_connector.svg (100%) rename docs/{ => design}/diagrams/data_adapter_selection_sequence.puml (69%) create mode 100644 docs/design/diagrams/data_adapter_selection_sequence.svg rename docs/{diagrams/data_flow_to_emitter_sequence.puml => design/diagrams/data_flow_sequence.puml} (96%) create mode 100644 docs/design/diagrams/data_flow_sequence.svg rename docs/{ => design}/diagrams/freyja_components.puml (68%) create mode 100644 docs/design/diagrams/freyja_components.svg rename docs/{ => design}/diagrams/mapping_service_to_cartographer_sequence.puml (100%) rename docs/{ => design}/diagrams/mapping_service_to_cartographer_sequence.svg (100%) delete mode 100644 docs/diagrams/data_adapter_selection_sequence.svg delete mode 100644 docs/diagrams/data_flow_to_emitter_sequence.svg delete mode 100644 docs/diagrams/freyja_components.svg delete mode 100644 docs/quickstart.md rename docs/{ => tutorials}/config-overrides.md (87%) rename docs/{ => tutorials}/custom-adapters.md (72%) create mode 100644 docs/tutorials/quickstart.md diff --git a/.accepted_words.txt b/.accepted_words.txt index 5e8d3662..9ac37818 100644 --- a/.accepted_words.txt +++ b/.accepted_words.txt @@ -42,6 +42,8 @@ csproj csr cv cvd +DataAdapter +DataAdapterFactory depgen der dev @@ -98,6 +100,7 @@ launchSetting libs libssl lifecycle +loopback mailto ManagedSubscribeDataAdapter MappingAdapter @@ -160,6 +163,7 @@ signkey snapd src SSL +standalone stdout STRUCT struct diff --git a/README.md b/README.md index 300b107e..2fc13b93 100644 --- a/README.md +++ b/README.md @@ -40,9 +40,9 @@ This guide uses `apt` as the package manager in the examples. You may need to su To use Freyja, you will need to implement some adapters and write the main executable that will run the Freyja application. -For a guide on how to get started quickly by running some minimal examples, see the [Quickstart Guide](docs/quickstart.md). +For a guide on how to get started quickly by running some minimal examples, see the [Quickstart Guide](docs/tutorials/quickstart.md). -For more advanced topics on how to implement and use your own adapters, see the [Custom Adapters Guide](docs/custom-adapters.md). +For more advanced topics on how to implement and use your own adapters, see the [Custom Adapters Guide](docs/tutorials/custom-adapters.md). ## Why "Freyja"? diff --git a/adapters/data/grpc_data_adapter/README.md b/adapters/data/grpc_data_adapter/README.md index 39c535a1..40d6e6c3 100644 --- a/adapters/data/grpc_data_adapter/README.md +++ b/adapters/data/grpc_data_adapter/README.md @@ -9,7 +9,7 @@ This adapter supports the following configuration settings: - `consumer_address`: The address for the adapter's consumer. The adapter's gRPC server will be hosted on this address. - `advertised_consumer_address`: (Optional) The advertised address for the adapter's consumer. This is the address that will be reported as the callback address to providers, enabling scenarios where the providers should use a different address from the actual hosting address. If not specified, this adapter will default to using the consumer address. -This adapter supports [config overrides](../../../docs/config-overrides.md). The override filename is `grpc_data_adapter_config.json`, and the default config is located at `res/grpc_data_adapter_config.default.json`. +This adapter supports [config overrides](../../../docs/tutorials/config-overrides.md). The override filename is `grpc_data_adapter_config.json`, and the default config is located at `res/grpc_data_adapter_config.default.json`. ## Integrating with this Adapter diff --git a/adapters/data/http_mock_data_adapter/README.md b/adapters/data/http_mock_data_adapter/README.md index 9bc8fa52..6017a562 100644 --- a/adapters/data/http_mock_data_adapter/README.md +++ b/adapters/data/http_mock_data_adapter/README.md @@ -9,4 +9,4 @@ This adapter supports the following configuration settings: - `callback_address`: The address for the adapter. This is the address that the Mock Digital Twin will use for callbacks. This should be a URI with no scheme and no port. - `starting_port`: The starting port number to use when creating adapters. The factory will increment the port it uses each time an adapter is created. -This adapter supports [config overrides](../../../docs/config-overrides.md). The override filename is `http_mock_data_adapter_config.json`, and the default config is located at `res/http_mock_data_adapter_config.default.json`. +This adapter supports [config overrides](../../../docs/tutorials/config-overrides.md). The override filename is `http_mock_data_adapter_config.json`, and the default config is located at `res/http_mock_data_adapter_config.default.json`. diff --git a/adapters/data/in_memory_mock_data_adapter/README.md b/adapters/data/in_memory_mock_data_adapter/README.md index 97bd8821..61902fcb 100644 --- a/adapters/data/in_memory_mock_data_adapter/README.md +++ b/adapters/data/in_memory_mock_data_adapter/README.md @@ -16,7 +16,7 @@ This adapter supports the following configuration settings: - `end`: The other bound for the signal value - `delta`: The amount to add to the signal value at each iteration. If this operation would exceed the specified bounds, then the signal value saturates at the boundary value. -This adapter supports [config overrides](../../../docs/config-overrides.md). The override filename is `in_memory_mock_data_adapter_config.json`, and the default config is located at `res/in_memory_mock_data_adapter_config.default.json`. +This adapter supports [config overrides](../../../docs/tutorials/config-overrides.md). The override filename is `in_memory_mock_data_adapter_config.json`, and the default config is located at `res/in_memory_mock_data_adapter_config.default.json`. ## Behavior diff --git a/adapters/data/managed_subscribe_data_adapter/README.md b/adapters/data/managed_subscribe_data_adapter/README.md index 849893c2..73965a6f 100644 --- a/adapters/data/managed_subscribe_data_adapter/README.md +++ b/adapters/data/managed_subscribe_data_adapter/README.md @@ -11,7 +11,7 @@ This adapter supports the following configuration settings: The above values define the frequency at which the adapter requests a provider to transfer data. -This adapter supports [config overrides](../../../docs/config-overrides.md). The override filename is `managed_subscribe_data_adapter_config.json`, and the default config is located at `res/managed_subscribe_data_adapter_config.default.json`. +This adapter supports [config overrides](../../../docs/tutorials/config-overrides.md). The override filename is `managed_subscribe_data_adapter_config.json`, and the default config is located at `res/managed_subscribe_data_adapter_config.default.json`. ## Integrating with this Adapter diff --git a/adapters/data/mqtt_data_adapter/README.md b/adapters/data/mqtt_data_adapter/README.md index 79e39f57..23e0dc7f 100644 --- a/adapters/data/mqtt_data_adapter/README.md +++ b/adapters/data/mqtt_data_adapter/README.md @@ -8,7 +8,7 @@ This adapter supports the following configuration settings: - `keep_alive_interval_s`: The keep alive interval for MQTT communications, in seconds -This adapter supports [config overrides](../../../docs/config-overrides.md). The override filename is `mqtt_data_adapter_config.json`, and the default config is located at `res/mqtt_data_adapter_config.default.json`. +This adapter supports [config overrides](../../../docs/tutorials/config-overrides.md). The override filename is `mqtt_data_adapter_config.json`, and the default config is located at `res/mqtt_data_adapter_config.default.json`. ## Integrating with this Adapter diff --git a/adapters/digital_twin/in_memory_mock_digital_twin_adapter/README.md b/adapters/digital_twin/in_memory_mock_digital_twin_adapter/README.md index 8cdabbf0..6f29802c 100644 --- a/adapters/digital_twin/in_memory_mock_digital_twin_adapter/README.md +++ b/adapters/digital_twin/in_memory_mock_digital_twin_adapter/README.md @@ -15,4 +15,4 @@ This adapter supports the following configuration settings: - `operations`: A list of operations that can be used to access this entity. - `uri`: The uri that is used to invoke a provider. This is used as the key when calling functions on the adapters. If you're using the `in-memory` protocol, requests are not actually submitted to this uri so it does not need to be a real endpoint. -This adapter supports [config overrides](../../../docs/config-overrides.md). The override filename is `in_memory_digital_twin_config.json`, and the default config is located at `res/in_memory_digital_twin_config.default.json`. +This adapter supports [config overrides](../../../docs/tutorials/config-overrides.md). The override filename is `in_memory_digital_twin_config.json`, and the default config is located at `res/in_memory_digital_twin_config.default.json`. diff --git a/adapters/digital_twin/mock_digital_twin_adapter/README.md b/adapters/digital_twin/mock_digital_twin_adapter/README.md index 1b882fbb..d6563bce 100644 --- a/adapters/digital_twin/mock_digital_twin_adapter/README.md +++ b/adapters/digital_twin/mock_digital_twin_adapter/README.md @@ -8,4 +8,4 @@ This adapter supports the following configuration settings: - `digital_twin_service_uri`: the base uri for the Mock Digital Twin Service -This adapter supports [config overrides](../../../docs/config-overrides.md). The override filename is `mock_digital_twin_adapter_config.json`, and the default config is located at `res/mock_digital_twin_adapter_config.default.json`. +This adapter supports [config overrides](../../../docs/tutorials/config-overrides.md). The override filename is `mock_digital_twin_adapter_config.json`, and the default config is located at `res/mock_digital_twin_adapter_config.default.json`. diff --git a/adapters/mapping/in_memory_mock_mapping_adapter/README.md b/adapters/mapping/in_memory_mock_mapping_adapter/README.md index 838a5611..de88c98c 100644 --- a/adapters/mapping/in_memory_mock_mapping_adapter/README.md +++ b/adapters/mapping/in_memory_mock_mapping_adapter/README.md @@ -16,7 +16,7 @@ This adapter supports the following configuration settings: - `emit_on_change`: a boolean indicating whether data emission should be skipped if the value hasn't changed since the last emission. Set to `true` to enable this behavior. - `conversion`: a conversion that should be applied. Set to `null` if no conversion is needed. Otherwise the conversion is configured with the `mul` and `offset` properties, and the value `y` that is emitted is calculated as `y = mul * x + offset`. Note that conversions are only supported for signal values which can be parsed as `f64`. -This adapter supports [config overrides](../../../docs/config-overrides.md). The override filename is `mock_mapping_config.json`, and the default config is located at `res/mock_mapping_config.default.json`. +This adapter supports [config overrides](../../../docs/tutorials/config-overrides.md). The override filename is `mock_mapping_config.json`, and the default config is located at `res/mock_mapping_config.default.json`. ## Behavior diff --git a/adapters/mapping/mock_mapping_service_adapter/README.md b/adapters/mapping/mock_mapping_service_adapter/README.md index a9a37de6..c0b60aa9 100644 --- a/adapters/mapping/mock_mapping_service_adapter/README.md +++ b/adapters/mapping/mock_mapping_service_adapter/README.md @@ -20,4 +20,4 @@ This adapter supports the following configuration settings: - `retry_interval_ms`: the interval between subsequent retry attempts, in milliseconds - `mock_mapping_service_url`: the url for the Mock Mapping Service -This adapter supports [config overrides](../../../docs/config-overrides.md). The override filename is `mock_mapping_adapter_config.json`, and the default config is located at `res/mock_mapping_adapter_config.default.json`. +This adapter supports [config overrides](../../../docs/tutorials/config-overrides.md). The override filename is `mock_mapping_adapter_config.json`, and the default config is located at `res/mock_mapping_adapter_config.default.json`. diff --git a/docs/design/README.md b/docs/design/README.md index 24c52465..54f00af2 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -14,48 +14,92 @@ The Software-Defined Vehicle will need to connect to the cloud for scenarios suc ## Architecture -At its core, Freyja consists of two main components: the **cartographer** and the **emitter**. In addition to these core components, there are multiple interfaces with external components that define how Freyja interacts with the cloud and the rest of the Software Defined Vehicle. There are interfaces for the in-vehicle digital twin (such as Ibeji), the mapping service (provided by customers), and the cloud digital twin provider (such as Azure or AWS). Below is a high-level diagram of the Freyja components: +At its core, Freyja consists of the following primary components: the **cartographer**, the **emitter**, the **data adapter selector**, and the **signal store**. In addition to these core components, there are multiple interfaces with external components that define how Freyja interacts with the cloud and the rest of the Software Defined Vehicle. There are interfaces for the in-vehicle digital twin service (such as Ibeji), the mapping service (authored by users), the cloud digital twin provider (such as Azure or AWS), and the digital twin providers (authored by users). Below is a high-level diagram of the Freyja components: -![Component Diagram](../diagrams/freyja_components.svg) +![Component Diagram](./diagrams/freyja_components.svg) -In a typical life cycle, the Freyja application will start up, discover Ibeji via Chariott or a static configuration, then connect to the mapping service to obtain a digital twin map. This map will define which signals need to be synced with the cloud digital twin, how often they need to be synced, and how the data should be transformed or packaged. Once a mapping is obtained, Freyja will connect to the providers and begin emitting their data according to the mapping. In case of changes on either the device or vehicle side, the mapping is dynamic and can be updated as required to add, remove, or modify the signals that are being emitted. +In a typical life cycle, the Freyja application will start up, discover Ibeji via Chariott or a static configuration, then connect to the mapping service to obtain an entity map. This map will define which signals need to be synced with the cloud digital twin, how often they need to be synced, and how the data should be transformed or packaged. Once a mapping is obtained, Freyja will connect to the providers and begin emitting their data according to the mapping. In case of changes on either the device or vehicle side, the mapping is dynamic and can be updated as required to add, remove, or modify the signals that are being emitted. + +The following is a more detailed diagram illustrating how the components interact and how a mapping results in signal data emissions: + +![Data Flow Sequence Diagram](./diagrams/data_flow_sequence.svg) ### Cartographer -The cartographer is the core component responsible for managing the digital twin mapping. The current implementation is very minimal and will poll the mapping adapter for updates. If there is an update pending, the cartographer will download it and update the application's stored mapping info. This is currently implemented as a shared application state which both the cartographer and emitter have access to. +The cartographer is the core component responsible for managing the entity map and tracking which signals should be synchronized to the cloud. + +The cartographer interfaces with the mapping adapter to poll the mapping service for updates. If there is an update pending, the cartographer will download it and interface with the digital twin adapter to look up the corresponding entity information. Then, the cartographer will use this information to register data adapters with the data adapter selector. Finally, the cartographer will populate the signal store with the signals that should be tracked. If any part of this process fails for a given entity, the signal will not be tracked and the cartographer will retry again at a later time. -![Sequence Diagram](../diagrams/mapping_service_to_cartographer_sequence.svg) +The following diagram illustrates the communication between the cartographer and the mapping service: + +![Sequence Diagram](./diagrams/mapping_service_to_cartographer_sequence.svg) ### Emitter -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. +The emitter is the core component responsible for actually emitting data. The emitter interfaces with the signal store to determine which signals should be emitted. Every signal present in the store will be emitted according to its mapping configuration. + +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, there can be a delay of up to `min(`*`I`*`)` before the signal is emitted, where *`I`* is the set of intervals for signals already being tracked. + +### Data Adapter Selector + +The data adapter selector is the core component responsible for managing communication with data adapters. It behaves like a gateway service and allows callers to interact with the correct data adapter for a given entity. + +The data adapter selector's main interface is the `create_or_update_adapter` function, which accepts an entity description as an argument. When calling this function, the data adapter selector will first use the entity's endpoint information to search for an existing adapter that can handle the requested entity. If no such adapter is found, the entity's protocol and operation are used to search for an adapter type that can handle that entity, and then an adapter is created. In either case, the new entity is registered with the adapter, which then interfaces with that entity's endpoint to obtain data. + +The data adapter selector also supports "loopback" functionality. When registering an entity with an adapter, the adapter may return a request for a loopback with updated entity info. This indicates to the selector that the matched adapter cannot handle the originally requested entity directly, but has modified its contents to redirect it to another adapter. This enables scenarios such as managed subscribe to perform pre-processing on entities while recycling other data adapter implementations which are independent of managed subscriptions. For more information on the managed subscribe functionality, see the [Eclipse Agemo project](https://github.com/eclipse-chariott/agemo). + +Below is a sequence diagram illustrating the data adapter selection process: -![Data Flow to Emitter Sequence Diagram](../diagrams/data_flow_to_emitter_sequence.svg) +![Data Adapter Selector Sequence](./diagrams/data_adapter_selection_sequence.svg) + +### Signal Store + +The signal store is the core component responsible for managing signal values. The signal store is considered to be the source of truth for which signals should be emitted, how they should be emitted, and what the most up-to-date value is for each signal. Each other core component interfaces with the signal store in some way to track, read, and write signal values. + +Note that the signal store is not intended to be a complete mirror of the vehicle signal state, but rather tracks only the signals of interest to Freyja. ### External Interfaces Freyja has the following interfaces for external components: -Component|Examples|Interface Trait|Description +Component|Interface Traits|Description|Examples -|-|-|- -In-Vehicle Digital Twin|Ibeji and its providers|`DigitalTwinAdapter`|Communicates with the in-vehicle digital twin to get signal values during emission. Often referred to as "DT Adapter" -Mapping Service|`MockMappingService`, other customer-provided implementations|`MappingAdapter`|Communicates with the mapping service -Cloud Digital Twin|Azure, AWS|`CloudAdapter`|Communicates with the cloud digital twin provider +In-Vehicle Digital Twin|`DigitalTwinAdapter`|Communicates with the in-vehicle digital twin service to get entity information|Ibeji Digital Twin Service +In-Vehicle Data Providers|`DataAdapter` and `DataAdapterFactory`|Communicates with the in-vehicle data providers to retrieve entity signal values|Ibeji sample providers +Mapping Service|`MappingAdapter`|Communicates with the mapping service|`MockMappingService`, other customer-provided implementations +Cloud Digital Twin|`CloudAdapter`|Communicates with the cloud digital twin provider|Azure, AWS All of these interfaces are defined as traits with async functions in the `contracts/src` folder. #### In-Vehicle Digital Twin Interface -The digital twin adapter interfaces with a digital twin service to get entity information. The [Ibeji Project](https://github.com/eclipse-ibeji/ibeji) is an example of such a service. This interface requires the following function implementations: +The digital twin adapter interfaces with a digital twin service to get entity information. The [Eclipse Ibeji project](https://github.com/eclipse-ibeji/ibeji) is an example of such a service. This interface requires the following function implementations: - `create_new`: Serves as an integration point for the core Freyja components. This function will be called by the `freyja_main` function to create an instance of your adapter. - `find_by_id`: Queries the digital twin service for information about the requested entity. This information will later be used to set up a communication pipeline with that entity's provider. Although this component is built with the same pluggable model as other external interfaces, it is being designed closely together with other SDV components. As a result, it is strongly suggested to use the provided SDV implementation of this interface, and this implementation should be sufficient for most production scenarios. +#### In-Vehicle Data Provider Interface + +The data adapters interface with providers to retrieve data from entities, such as signal values. This data will ultimately be pushed to the cloud digital twin by the emitter and cloud adapter. There are two interfaces related to the data provider interface: `DataAdapter` and `DataAdapterFactory`. + +The `DataAdapter` interface requires the following function implementations: + +- `create_new`: Serves as an integration point. This is typically used by the corresponding `DataAdapterFactory` implementation of `create_adapter` (see below). +- `start`: Starts the data adapter. This function should not block indefinitely. Any required servers, listeners, and so on should be initialized as a separate thread or task. +- `send_request_to_provider`: Sends a request to a provider to publish data immediately. In most use cases data is updated asynchronously with a publisher-subscriber model, but this function allows for a more traditional synchronous-like interface. Note that the adapter is still expected to update data in the signal store asynchronously, as the return type of the function does not contain any data. +- `register_entity`: Registers an entity with this adapter. + +The `DataAdapterFactory` interface requires the following function implementations: + +- `create_new`: Serves as an integration point for the core Freyja components. This function will be called by the `freyja_main!` macro to create an instance of your factory. +- `is_supported`: Determines whether this factory can create an adapter that supports the requested entity. Typically this decision is made by inspecting the entity's endpoints to see if any of the protocols and operations are known to the corresponding data adapter type. If an entity is supported, this function should select and return one of the entity's endpoints that will be used when creating the adapter. +- `create_adapter`: Creates a data adapter. + #### Mapping Adapter Interface -Freyja communicates with a mapping service via the `MappingAdapter` trait to get information about how to package data during emission. This trait defines the following functions: +Freyja communicates with a mapping service via the `MappingAdapter` trait to get information about which signals to track and how to package data during emission. This trait defines the following functions: - `create_new`: Serves as an integration point for the core Freyja components. This function will be called by the `freyja_main` function to create an instance of your adapter. - `check_for_work`: Because mappings returned from the `get_mapping` API can potentially be large, this method is used to first poll for changes before calling that API. If the result is false, then the cartographer will not invoke the `get_mapping` API until it polls again. @@ -66,21 +110,19 @@ For more information about the mapping service and how this interface is used, s #### Cloud Digital Twin Interface -The cloud adapter interfaces with the cloud or a cloud connector to emit data to a digital twin. It's recommended to route communication through a cloud connector on the device to help manage authentication, batching, and other policies that may be useful for automotive scenarios. This interface requires the following function implementations: +The cloud adapter interfaces with the cloud or a cloud connector to emit data to a remote data store, such as a digital twin. It's recommended to route communication through a cloud connector on the device to help manage authentication, batching, and other policies that may be useful for automotive scenarios which are not natively supported by Freyja. This interface requires the following function implementations: - `create_new`: Serves as an integration point for the core Freyja components. This function will be called by the `freyja_main` function to create an instance of your adapter. - `send_to_cloud`: Sends data to the cloud or cloud connector. The request includes a `cloud_signal` property which is a hash map of custom key-value arguments, and the signal value will be converted to a string. ### Mapping Service -Freyja relies on an external mapping service to define how data should be synced to the cloud. The implementation of this service is intentionally left undefined as it's expected that it will vary on a per-customer basis. We only define the interface that the Freyja application expects and provide some sample mock services. +Freyja relies on an external mapping service to define how data should be synced to the cloud. The implementation of this service is intentionally left undefined as it's expected that it will vary on a per-user basis. Freyja only defines the interface and provides some mocks for testing. At a high level, this component should be able to identify the vehicle making a request and either look up or compute a mapping for that vehicle. This could be done with a static vehicle-id-to-mapping database, or it might be more dynamic and linked to the cloud digital twin solution to compute mappings on the fly. -The reference architecture here specifies the mapping service as a cloud service with which Freyja communicates, though an alternate reference architecture may have Freyja communicating with another application on the vehicle which caches data from the cloud service. Yet another potential architecture may leverage the vehicle's OTA solution to update the mapping data on a local mapping service rather than having a dedicated cloud mapping service. Freyja supports a flexible pluggable system to enable customers to select the implementation that best meets their needs. +The reference architecture in this document specifies the mapping service as a cloud service with which Freyja communicates, though an alternative architecture may have Freyja communicating with another application on the vehicle which caches data from the cloud service. Yet another potential architecture may leverage the vehicle's OTA solution to update the mapping data on a local mapping service rather than having a dedicated cloud mapping service. Freyja supports a flexible and pluggable system to enable users to select the implementation that best meets their needs. ## Future Work -Freyja currently only supports device-to-cloud (D2C) scenarios. Cloud-to-device (C2D) scenarios are planned for the future, though there are no current designs for this feature. - -In addition, Freyja currently only supports a built-in set of protocols and data schemas for communication with providers. In the future, this will have a pluggable model similar to other adapters to enable custom protocols. +Freyja currently only supports device-to-cloud (D2C) scenarios. Cloud-to-device (C2D) scenarios are planned for the future, though there are no current designs or timelines for this feature. diff --git a/docs/diagrams/azure_digital_twins_cloud_connector.puml b/docs/design/diagrams/azure_digital_twins_cloud_connector.puml similarity index 100% rename from docs/diagrams/azure_digital_twins_cloud_connector.puml rename to docs/design/diagrams/azure_digital_twins_cloud_connector.puml diff --git a/docs/diagrams/azure_digital_twins_cloud_connector.svg b/docs/design/diagrams/azure_digital_twins_cloud_connector.svg similarity index 100% rename from docs/diagrams/azure_digital_twins_cloud_connector.svg rename to docs/design/diagrams/azure_digital_twins_cloud_connector.svg diff --git a/docs/diagrams/azure_mqtt_cloud_connector.puml b/docs/design/diagrams/azure_mqtt_cloud_connector.puml similarity index 100% rename from docs/diagrams/azure_mqtt_cloud_connector.puml rename to docs/design/diagrams/azure_mqtt_cloud_connector.puml diff --git a/docs/diagrams/azure_mqtt_cloud_connector.svg b/docs/design/diagrams/azure_mqtt_cloud_connector.svg similarity index 100% rename from docs/diagrams/azure_mqtt_cloud_connector.svg rename to docs/design/diagrams/azure_mqtt_cloud_connector.svg diff --git a/docs/diagrams/data_adapter_selection_sequence.puml b/docs/design/diagrams/data_adapter_selection_sequence.puml similarity index 69% rename from docs/diagrams/data_adapter_selection_sequence.puml rename to docs/design/diagrams/data_adapter_selection_sequence.puml index b24d96fb..36ae45db 100644 --- a/docs/diagrams/data_adapter_selection_sequence.puml +++ b/docs/design/diagrams/data_adapter_selection_sequence.puml @@ -9,13 +9,23 @@ autonumber "Freyja Cartographer"->"Data Adapter Selector": create_or_update_adapter(entity) -"Data Adapter Selector"->"Data Adapter Selector": Lookup adapter in selector's local cache +"Data Adapter Selector"->"Data Adapter Selector": Look up 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 +loop While adapters return loopback requests "Data Adapter Selector"->"Data Adapter": Register the new entity +"Data Adapter Selector"<-"Data Adapter": Entity registration response +note left +The entity registration response +can indicate success or failure, +or request a loopback with +updated entity information. +end note +end + "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 diff --git a/docs/design/diagrams/data_adapter_selection_sequence.svg b/docs/design/diagrams/data_adapter_selection_sequence.svg new file mode 100644 index 00000000..ccb64c04 --- /dev/null +++ b/docs/design/diagrams/data_adapter_selection_sequence.svg @@ -0,0 +1,47 @@ +Freyja CartographerFreyja CartographerData Adapter SelectorData Adapter SelectorData AdapterData AdapterIn-Vehicle Digital Twin ProviderIn-Vehicle Digital Twin ProviderSelection of a Data Adapter1create_or_update_adapter(entity)2Look up adapter in selector's local cachealt[Matching Data Adapter Doesn't Exist]3Create a data adapter associated with the entity endpointloop[While adapters return loopback requests]4Register the new entity5Entity registration responseThe entity registration responsecan indicate success or failure,or request a loopback withupdated entity information.6Map entity to adapter in selector's local cache7Call get or subscribe for values8Return valuesSelection of a Data Adapter \ No newline at end of file diff --git a/docs/diagrams/data_flow_to_emitter_sequence.puml b/docs/design/diagrams/data_flow_sequence.puml similarity index 96% rename from docs/diagrams/data_flow_to_emitter_sequence.puml rename to docs/design/diagrams/data_flow_sequence.puml index 3cf9f9bf..116497de 100644 --- a/docs/diagrams/data_flow_to_emitter_sequence.puml +++ b/docs/design/diagrams/data_flow_sequence.puml @@ -13,7 +13,7 @@ participant "Provider" autonumber -== Data Flow to Emitter == +== Entity Registration == "Cartographer"->"Digital Twin Adapter": Request DTDL for mapped entites "Digital Twin Adapter"->"Ibeji": Send find_by_id request(s) @@ -29,6 +29,10 @@ end "Data Adapter"->"Data Adapter Selector": Register entity response "Data Adapter Selector"->"Cartographer": Register entity response "Cartographer"->"Signal Store": Track Signals + +== Data Collection and Emission == + +loop alt Entity doesn't support subscribe "Emitter"->"Data Adapter Selector": Request signal value "Data Adapter Selector"->"Data Adapter Selector": Select correct Data Adapter @@ -47,6 +51,6 @@ end "Emitter"<-"Signal Store": Signal value response end "Emitter"->"Cloud Digital Twin": Emit signal data +end -== Data Flow to Emitter == @enduml diff --git a/docs/design/diagrams/data_flow_sequence.svg b/docs/design/diagrams/data_flow_sequence.svg new file mode 100644 index 00000000..067a5b7f --- /dev/null +++ b/docs/design/diagrams/data_flow_sequence.svg @@ -0,0 +1,69 @@ +FreyjaCloud Digital TwinCloud Digital TwinEmitterEmitterSignal StoreSignal StoreCartographerCartographerDigital Twin AdapterDigital Twin AdapterData Adapter SelectorData Adapter SelectorData AdapterData AdapterIbejiIbejiProviderProviderEntity Registration1Request DTDL for mapped entites2Send find_by_id request(s)3Respond with entity data4Respond with entity data5Create or update data adapter with entity data6Select correct Data Adapter7Register entityalt[Entity supports subscribe]8Subscribe9Subscribe Response10Register entity response11Register entity response12Track SignalsData Collection and Emissionloopalt[Entity doesn't support subscribe]13Request signal value14Select correct Data Adapter15Request signal value16Request signal value17Signal value response18Signal value response19Signal value responsealt[Entity supports subscribe]loop[Provider publishes data asynchronously]20Publish data21Update store22Request signal value23Signal value response24Emit signal data \ No newline at end of file diff --git a/docs/diagrams/freyja_components.puml b/docs/design/diagrams/freyja_components.puml similarity index 68% rename from docs/diagrams/freyja_components.puml rename to docs/design/diagrams/freyja_components.puml index 93a95635..f00c2552 100644 --- a/docs/diagrams/freyja_components.puml +++ b/docs/design/diagrams/freyja_components.puml @@ -11,7 +11,10 @@ cloud { package "Vehicle" { frame "Freyja" { [Cartographer] + interface "Digital Twin Adapter" + interface "Mapping Adapter" [Emitter] + interface "Cloud Adapter" database "Signal Store" [Data Adapter Selector] node "Data Adapters" { @@ -32,12 +35,15 @@ package "Vehicle" { [Mapping Service] as ivMappingSvc } -[Emitter] -u-> [Cloud Connector] : Emit Data -[Cartographer] <-[norank]-> [ivMappingSvc] : Get Mapping +[Emitter] -u-> [Cloud Adapter] : Emit Data +[Cloud Adapter] -u-> [Cloud Connector] : Emit Data +[Cartographer] <-u-> [Mapping Adapter] : Get Mapping +[Mapping Adapter] <-[norank]-> [ivMappingSvc] : Get Mapping [ivMappingSvc] <.u.> [cloudMappingSvc] [Cloud Connector] -u-> [Cloud Digital Twin] -[Cartographer] .d.> [Chariott] : Discover Ibeji (optional) -[Cartographer] -d-> [ivdts] : Discover Providers +[Cartographer] -d-> [Digital Twin Adapter] +[Digital Twin Adapter] .d.> [Chariott] : Discover Ibeji (optional) +[Digital Twin Adapter] -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 diff --git a/docs/design/diagrams/freyja_components.svg b/docs/design/diagrams/freyja_components.svg new file mode 100644 index 00000000..f186f184 --- /dev/null +++ b/docs/design/diagrams/freyja_components.svg @@ -0,0 +1,106 @@ +VehicleFreyjaData AdaptersIbejiDigital Twin ProvidersMapping ServiceCloud Digital TwinChariottCloud ConnectorMapping ServiceCartographerDigital Twin AdapterMapping AdapterEmitterCloud AdapterSignal StoreData Adapter SelectorData AdapterIn-Vehicle Digital Twin ServiceDigital Twin ProviderEmit DataEmit DataGet MappingGet MappingDiscover Ibeji (optional)Discover ProvidersTrack SignalsRegister AdaptersRegister AdaptersCollect dataUpdate signal valuesRetrieve data \ No newline at end of file diff --git a/docs/diagrams/mapping_service_to_cartographer_sequence.puml b/docs/design/diagrams/mapping_service_to_cartographer_sequence.puml similarity index 100% rename from docs/diagrams/mapping_service_to_cartographer_sequence.puml rename to docs/design/diagrams/mapping_service_to_cartographer_sequence.puml diff --git a/docs/diagrams/mapping_service_to_cartographer_sequence.svg b/docs/design/diagrams/mapping_service_to_cartographer_sequence.svg similarity index 100% rename from docs/diagrams/mapping_service_to_cartographer_sequence.svg rename to docs/design/diagrams/mapping_service_to_cartographer_sequence.svg diff --git a/docs/diagrams/data_adapter_selection_sequence.svg b/docs/diagrams/data_adapter_selection_sequence.svg deleted file mode 100644 index 787d6f07..00000000 --- a/docs/diagrams/data_adapter_selection_sequence.svg +++ /dev/null @@ -1,37 +0,0 @@ -Freyja CartographerFreyja CartographerData Adapter SelectorData Adapter SelectorData AdapterData AdapterIn-Vehicle Digital Twin ProviderIn-Vehicle Digital Twin ProviderSelection of a Data Adapter1create_or_update_adapter(entity)2Lookup adapter in selector's local cachealt[Matching Data Adapter Doesn't Exist]3Create a data adapter associated with the entity endpoint4Register the new entity5Map entity to adapter in selector's local cache6Call get or subscribe for values7Return valuesSelection of a Data Adapter \ No newline at end of file diff --git a/docs/diagrams/data_flow_to_emitter_sequence.svg b/docs/diagrams/data_flow_to_emitter_sequence.svg deleted file mode 100644 index 381d8af1..00000000 --- a/docs/diagrams/data_flow_to_emitter_sequence.svg +++ /dev/null @@ -1,65 +0,0 @@ -FreyjaCloud Digital TwinCloud Digital TwinEmitterEmitterSignal StoreSignal StoreCartographerCartographerDigital Twin AdapterDigital Twin AdapterData Adapter SelectorData Adapter SelectorData AdapterData AdapterIbejiIbejiProviderProviderData Flow to Emitter1Request DTDL for mapped entites2Send find_by_id request(s)3Respond with entity data4Respond with entity data5Create or update data adapter with entity data6Select correct Data Adapter7Register entityalt[Entity supports subscribe]8Subscribe9Subscribe Response10Register entity response11Register entity response12Track Signalsalt[Entity doesn't support subscribe]13Request signal value14Select correct Data Adapter15Request signal value16Request signal value17Signal value response18Signal value response19Signal value responsealt[Entity supports subscribe]loop[Provider publishes data asynchronously]20Publish data21Update store22Request signal value23Signal value response24Emit signal dataData Flow to Emitter \ No newline at end of file diff --git a/docs/diagrams/freyja_components.svg b/docs/diagrams/freyja_components.svg deleted file mode 100644 index 5b16917a..00000000 --- a/docs/diagrams/freyja_components.svg +++ /dev/null @@ -1,94 +0,0 @@ -VehicleFreyjaData AdaptersIbejiDigital Twin ProvidersMapping ServiceCloud Digital TwinChariottCloud ConnectorMapping ServiceCartographerEmitterSignal StoreData Adapter SelectorData AdapterIn-Vehicle Digital Twin ServiceDigital Twin ProviderEmit DataGet MappingDiscover Ibeji (optional)Discover ProvidersTrack SignalsRegister AdaptersRegister AdaptersCollect dataUpdate signal valuesRetrieve data \ No newline at end of file diff --git a/docs/quickstart.md b/docs/quickstart.md deleted file mode 100644 index f11c143a..00000000 --- a/docs/quickstart.md +++ /dev/null @@ -1,81 +0,0 @@ - -# Freyja Quickstart Guide - -The Freyja project provides some example adapter implementations that can be used to get started quickly and experiment with Freyja without needing to write any code. For more information about the example adapters that Freyja provides, including links to documentation on how to configure them for more complex scenarios, see the [Appendix](#appendix-a). - -## Build - -In order to run the examples mentioned in this document, you will first need to build them with the following command: - -```shell -cargo build --examples -``` - -## Example Scenarios - -### In-Memory Example - -This example uses the in-memory mock adapters to emulate the behavior of external components from entirely within the memory of the Freyja application. This example does not require any other services to be configured or running in order to function properly, and there will be no external API calls made by the Freyja core components. - -This example is ideal for getting started with minimal effort or configuration. However, it does not offer precise control over how the mocked interfaces behave during runtime. This example is most commonly used for testing scenarios. - -To run this sample, run the following command: - -```shell -cargo run --example in-memory -``` - -Note that there is also an `in-memory-with-fn` example with identical behavior. The difference between these two examples is that they show different ways of integrating the same adapters with the Freyja core components, which is an advanced topic covered in the [Custom Adapters Guide](./custom-adapters.md). - -### Mock Services Example - -This example uses the Mock Digital Twin Service and Mock Mapping Service. The behavior is very similar to the in-memory example, but with two key differences: - -1. The mapping adapter and digital twin adapter function as clients to external services rather than handling everything in-memory. These external services are mock versions of the mapping and digital twin services which run as binaries on the same device. -1. The mock services allow for more precise control over when their state changes. Users can advance the state of the applications by interacting with their terminal interfaces. - -This example is ideal if you need to manually control when signals or mappings are added or removed from the application, thus affecting what data gets emitted by Freyja. This example is most commonly used for demo scenarios. - -To run this sample, follow these steps: - -1. Run the Mock Digital Twin Service. To do so, open a new terminal window and run the following: - - cargo run --bin mock-digital-twin - - Note that with the default configuration, the mock is initialized with no entities activated. Whenever you press Enter in the mock's terminal window, the mock's state will change to include additional entities that will be returned by the `find_by_id` API. Using the default configuration, up to three entities can be added one at a time when pressing Enter. - -1. Run the Mock Mapping Service. To do so, open a new terminal window and run the following: - - cargo run --bin mock-mapping-service - - Note that with the default configuration, the mock is initialized with no mappings activated. Whenever you press Enter in the mock's terminal window, the mock's state will change to include additional mappings that will be returned by the `get_mapping` API. Using the default configuration, up to three mappings can be added one at a time when pressing Enter. - -1. Run the example. To do so, run the following in the original terminal window: - - cargo run --example mocks - -# Appendix A - -This appendix lists the sample adapters that are provided in this repository. These are self-contained and do not require anything outside of this repository to be set up. More detailed adapters which interface with external components can be found in the [Ibeji Example Applications repository](https://github.com/eclipse-ibeji/ibeji-example-applications). - -## Digital Twin Adapters - -- [In-Memory Mock Digital Twin Adapter](../adapters/digital_twin/in_memory_mock_digital_twin_adapter/README.md): Emulates a Digital Twin Service entirely within the memory of the Freyja application. -- [Mock Digital Twin Adapter](../adapters/digital_twin/mock_digital_twin_adapter/README.md): Communicates with the [Mock Digital Twin](../mocks/mock_digital_twin/README.md), which is an executable that mocks the Digital Twin Service. The behavior is very similar to the in-memory mock, but the application is interactive and allows users to add or remove entities from the mocked digital twin by pressing enter to advance through configurable states. - -## Mapping Adapters - -- [In-Memory Mock Mapping Adapter](../adapters/mapping/in_memory_mock_mapping_adapter/README.md): Emulates a mapping service entirely within the memory of the Freyja application. -- [Mock Mapping Service Adapter](../adapters/mapping/mock_mapping_service_adapter/README.md): Communicates with the [Mock Mapping Service](../mocks/mock_mapping_service/README.md), which is an executable that mocks a Mapping Service. The behavior is very similar to the in-memory mock, but the application is interactive and allows users to add or remove mappings by pressing enter to advance through configurable states. - -## Digital Twin Adapters - -- [In-Memory Mock Cloud Adapter](../adapters/cloud/in_memory_mock_cloud_adapter/README.md): Emulates a Cloud Connector entirely within the memory of the Freyja application. When data is emitted to this adapter it will be printed to the console window. - -## Data Adapters - -- [In-Memory Mock Data Adapter](../adapters/data/in_memory_mock_data_adapter/README.md): Interfaces with the In-Memory Mock Digital Twin Adapter and intended for use with it. -- [HTTP Mock Data Adapter](../adapters/data/http_mock_data_adapter/README.md): Interfaces with the Mock Digital Twin Adapter and intended for use with it. -- [gRPC Data Adapter](../adapters/data/grpc_data_adapter/README.md): Interfaces with providers that communicate via gRPC. Integrated with specific Ibeji samples. -- [MQTT Data Adapter](../adapters/data/mqtt_data_adapter/README.md): Interfaces with providers that communicate via MQTT. -- [Managed Subscribe Data Adapter](../adapters/data/managed_subscribe_data_adapter/README.md): Interfaces with providers that leverage the managed subscribe feature of Ibeji. diff --git a/docs/config-overrides.md b/docs/tutorials/config-overrides.md similarity index 87% rename from docs/config-overrides.md rename to docs/tutorials/config-overrides.md index 730a00da..4e83812a 100644 --- a/docs/config-overrides.md +++ b/docs/tutorials/config-overrides.md @@ -2,10 +2,10 @@ Many Freyja components support configuration overrides to enable users to override default settings and provide custom configuration. This is achieved with configuration layering. Components using this configuration strategy will define a default config, which is often suitable for basic scenarios or getting started quickly. This default config can be overridden at runtime using custom values. When loading configuration, a component will probe for and unify config in the following order, with values near the end of the list taking higher precedence: -- The default config +- The default config. This is typically included in the component's source tree and gets placed in the build output directory. - A config file in the working directory of the executable (for example, the directory you were in when you ran the `cargo run` command) - `$FREYJA_HOME/config/{config_name}.json`. If you have not set a `$FREYJA_HOME` directory, this defaults to: - Unix: `$HOME/.freyja/config/{config_name}.json` - Windows: `%USERPROFILE%\.freyja\config\{config_name}.json` (note that Windows support is not guaranteed by Freyja) -Because the config is layered, the overrides can be partially defined and only specify the top-level configuration fields that should be overridden. Anything not specified in an override file will use the default value. +Because the config is layered, the overrides can be partially defined and only specify the top-level configuration fields that should be overridden. Anything not specified in an override file will use the default value, if available. diff --git a/docs/custom-adapters.md b/docs/tutorials/custom-adapters.md similarity index 72% rename from docs/custom-adapters.md rename to docs/tutorials/custom-adapters.md index 1c3e2ac4..2b01e825 100644 --- a/docs/custom-adapters.md +++ b/docs/tutorials/custom-adapters.md @@ -1,17 +1,19 @@ # Writing Custom Adapters and Integrating with Freyja -Freyja allows users to bring their own implementations of various traits which interface with external components. This is achieved by exposing the core functionality of Freyja as a library function and requiring users to author the final binary package to link everything together. In most cases this can be simplified by using a provided macro, but for scenarios that require more complex setup for the adapters the library function can be called manually. +Freyja allows users to bring their own implementations of various traits which interface with external components. This is achieved by exposing the core functionality of Freyja as a library function and requiring users to author the final binary package to link everything together. + +For more examples of Freyja adapters and applications, see the [Ibeji Example Applications repository](https://github.com/eclipse-ibeji/ibeji-example-applications). ## How to Author a Custom Adapter -Freyja supports custom implementations of the `DigitalTwinAdapter`, `CloudAdapter`, and `MappingAdapter` interfaces. To refer to these traits in your implementation, you will need to take a dependency on the `freyja-common` crate. The following `Cargo.toml` snippet shows how you can include this dependency: +Freyja supports custom implementations of the `DigitalTwinAdapter`, `CloudAdapter`, `MappingAdapter`, `DataAdapter`, and `DataAdapterFactory` interfaces. To refer to these traits in your implementation, you will need to take a dependency on the `freyja-common` crate. The following `Cargo.toml` snippet shows how you can include this dependency: ```toml [dependencies] freyja-common = { git = "https://github.com/eclipse-ibeji/freyja" } ``` -For more information about the adapter interfaces, see [the design doc](./design/README.md#external-interfaces). +For more information about the adapter interfaces, see [the design doc](./../design/README.md#external-interfaces). ## How to Author a Freyja Application @@ -23,6 +25,6 @@ freyja = { git = "https://github.com/eclipse-ibeji/freyja" } tokio = { version = "1.0", features = ["macros"] } ``` -In most cases, the `main.rs` file can be implemented using the `freyja_main!` macro which will take care of writing some boilerplate code for you. This macro only needs adapter type names as input and will generate the main function signature and body. For an example of how to use this macro, see the code for the [in-memory example](../freyja/examples/in-memory.rs) or the [mock example](../freyja/examples/mocks.rs). +In most cases, the `main.rs` file can be implemented using the `freyja_main!` macro which will take care of writing some boilerplate code for you. This macro only needs adapter type names as input and will generate the main function signature and body. For an example of how to use this macro, see the code for the [in-memory example](../../freyja/examples/in-memory.rs) or the [mock example](../../freyja/examples/mocks.rs). -If you have a more complex scenario that requires some additional setup before running the `freyja_main` function, you can instead invoke it manually without using the macro. For an example of how to use this function and how to manually author the main function, see the code for the [in-memory-with-fn example](../freyja/examples/in-memory-with-fn.rs). +If you have a more complex scenario that requires some additional setup before running the `freyja_main` function, you can instead invoke it manually without using the macro. For an example of how to use this function and how to manually author the main function, see the code for the [in-memory-with-fn example](../../freyja/examples/in-memory-with-fn.rs). diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md new file mode 100644 index 00000000..00b093b5 --- /dev/null +++ b/docs/tutorials/quickstart.md @@ -0,0 +1,73 @@ + +# Freyja Quickstart Guide + +The Freyja project provides some example adapter implementations that can be used to get started quickly and experiment with Freyja without needing to write any code. For more information about the example adapters that Freyja provides, including links to documentation on how to configure them for more complex scenarios, see the [Appendix](#appendix-a). + +## Example Scenarios + +### In-Memory Example + +This standalone example uses the in-memory mock adapters to emulate the behavior of external components from entirely within the memory of the Freyja application. This example does not require any other services to be configured or running in order to function properly, and there will be no external API calls made by the Freyja core components. + +This example is ideal for getting started with minimal effort or configuration. However, it does not offer precise control over how the mocked interfaces behave during runtime. This example is most commonly used for testing scenarios. + +To run this sample, run the following command. This will build the example (if necessary) and then execute it: + +```shell +cargo run --example in-memory +``` + +Note that there is also an `in-memory-with-fn` example with identical behavior. The difference between these two examples is that they show different ways of integrating the same adapters with the Freyja core components, which is an advanced topic covered in the [Custom Adapters Guide](./custom-adapters.md). + +### Mock Services Example + +This example uses the Mock Digital Twin Service and Mock Mapping Service. The behavior is very similar to the in-memory example, but with two key differences: + +1. The mapping adapter and digital twin adapter function as clients to external services rather than handling everything in-memory. These external services are mock versions of the mapping and digital twin services which run as binaries on the same device. +1. The mock services allow for more precise control over when their state changes. Users can advance the state of the applications by interacting with their terminal interfaces. + +This example is ideal if you need to manually control when signals or mappings are added or removed from the application, thus affecting what data gets emitted by Freyja. This example is most commonly used for demo scenarios. + +To run this sample, follow these steps: + +1. Run the Mock Digital Twin Service. To do so, open a new terminal window and run the following: + + cargo run --bin mock-digital-twin + + Note that with the default configuration, the mock is initialized with no entities activated. Whenever you press Enter in the mock's terminal window, the mock's state will change to include additional entities that will be returned by the `find_by_id` API. Using the default configuration, up to three entities can be added one at a time when pressing Enter. + +1. Run the Mock Mapping Service. To do so, open a new terminal window and run the following: + + cargo run --bin mock-mapping-service + + Note that with the default configuration, the mock is initialized with no mappings activated. Whenever you press Enter in the mock's terminal window, the mock's state will change to include additional mappings that will be returned by the `get_mapping` API. Using the default configuration, up to three mappings can be added one at a time when pressing Enter. + +1. Run the example. To do so, run the following in the original terminal window. This will build the example (if necessary) and then execute it: + + cargo run --example mocks + +# Appendix A + +This appendix lists the sample that are provided in this repository. These are self-contained and do not require anything outside of this repository to be set up. More detailed adapters which interface with external components can be found in the [Ibeji Example Applications repository](https://github.com/eclipse-ibeji/ibeji-example-applications). + +## Digital Twin Adapters + +- [In-Memory Mock Digital Twin Adapter](../../adapters/digital_twin/in_memory_mock_digital_twin_adapter/README.md): Emulates a Digital Twin Service entirely within the memory of the Freyja application. +- [Mock Digital Twin Adapter](../../adapters/digital_twin/mock_digital_twin_adapter/README.md): Communicates with the [Mock Digital Twin](../../mocks/mock_digital_twin/README.md), which is an executable that mocks the Digital Twin Service. The behavior is very similar to the in-memory mock, but the application is interactive and allows users to add or remove entities from the mocked digital twin by pressing enter to advance through configurable states. + +## Mapping Adapters + +- [In-Memory Mock Mapping Adapter](../../adapters/mapping/in_memory_mock_mapping_adapter/README.md): Emulates a mapping service entirely within the memory of the Freyja application. +- [Mock Mapping Service Adapter](../../adapters/mapping/mock_mapping_service_adapter/README.md): Communicates with the [Mock Mapping Service](../../mocks/mock_mapping_service/README.md), which is an executable that mocks a Mapping Service. The behavior is very similar to the in-memory mock, but the application is interactive and allows users to add or remove mappings by pressing enter to advance through configurable states. + +## Digital Twin Adapters + +- [In-Memory Mock Cloud Adapter](../../adapters/cloud/in_memory_mock_cloud_adapter/README.md): Emulates a Cloud Connector entirely within the memory of the Freyja application. When data is emitted to this adapter it will be printed to the console window. + +## Data Adapters + +- [In-Memory Mock Data Adapter](../../adapters/data/in_memory_mock_data_adapter/README.md): Interfaces with the In-Memory Mock Digital Twin Adapter and intended for use with it. +- [HTTP Mock Data Adapter](../../adapters/data/http_mock_data_adapter/README.md): Interfaces with the Mock Digital Twin Adapter and intended for use with it. +- [gRPC Data Adapter](../../adapters/data/grpc_data_adapter/README.md): Interfaces with providers that communicate via gRPC. Integrated with specific Ibeji samples. +- [MQTT Data Adapter](../../adapters/data/mqtt_data_adapter/README.md): Interfaces with providers that communicate via MQTT. +- [Managed Subscribe Data Adapter](../../adapters/data/managed_subscribe_data_adapter/README.md): Interfaces with providers that leverage the managed subscribe feature of Ibeji. diff --git a/mocks/mock_digital_twin/README.md b/mocks/mock_digital_twin/README.md index 3736c7d1..341b7fcf 100644 --- a/mocks/mock_digital_twin/README.md +++ b/mocks/mock_digital_twin/README.md @@ -19,7 +19,7 @@ This mock supports the following configuration: - `end`: The other bound for the signal value - `delta`: The amount to add to the signal value at each iteration. If this operation would exceed the specified bounds, then the signal value saturates at the boundary value. -This mock supports [config overrides](../../docs/config-overrides.md). The override filename is `mock_digital_twin_config.json`, and the default config is located at `res/mock_digital_twin_config.default.json`. +This mock supports [config overrides](../../docs/tutorials/config-overrides.md). The override filename is `mock_digital_twin_config.json`, and the default config is located at `res/mock_digital_twin_config.default.json`. ## Behavior