From 58d184514c3ce1ed1024612eca95594ed8d6b497 Mon Sep 17 00:00:00 2001 From: ziliolu Date: Mon, 2 Jun 2025 18:03:16 +0100 Subject: [PATCH] Add architecture decision records for VSS naming convention and cross-compilation strategy --- .../0003-zenoh-with-influxdb-backend.md | 22 ++++++++++++ docs/architecture/decisions/0004-vss-model.md | 24 +++++++++++++ ...n-communication-between-jetson-and-rasp.md | 31 +++++++++++++++++ .../decisions/0011-qt-crosscompilation.md | 17 ++++++++++ .../0013-zenoh-with-shared-memory.md | 34 +++++++++++++++++++ ...d => 0014-levels-of-driving-automation.md} | 0 docs/architecture/decisions/DoxAdrIndex.md | 2 +- 7 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 docs/architecture/decisions/0003-zenoh-with-influxdb-backend.md create mode 100644 docs/architecture/decisions/0004-vss-model.md create mode 100644 docs/architecture/decisions/0005-can-communication-between-jetson-and-rasp.md create mode 100644 docs/architecture/decisions/0011-qt-crosscompilation.md create mode 100644 docs/architecture/decisions/0013-zenoh-with-shared-memory.md rename docs/architecture/decisions/{0013-levels-of-driving-automation.md => 0014-levels-of-driving-automation.md} (100%) diff --git a/docs/architecture/decisions/0003-zenoh-with-influxdb-backend.md b/docs/architecture/decisions/0003-zenoh-with-influxdb-backend.md new file mode 100644 index 0000000..02b2eb5 --- /dev/null +++ b/docs/architecture/decisions/0003-zenoh-with-influxdb-backend.md @@ -0,0 +1,22 @@ +# ADR 0003: Zenoh Router with InfluxDB Backend + +## Status +Accepted + +## Context +To enable efficient communication between the car and the cloud, we need a robust data routing and storage solution. Additionally, we aim to visualize measurements using Grafana. + +## Decision +We will deploy a Zenoh router running in the car, configured with an InfluxDB backend. This setup will allow: +- Real-time communication between the car and the cloud. +- Storage of measurement data in InfluxDB for later analysis. +- Integration with Grafana to create visual dashboards for measurement data. + +## Consequences +- The Zenoh router will handle data routing efficiently, enabling seamless cloud communication. +- InfluxDB will provide a reliable backend for storing time-series data. +- Future integration with Grafana will allow us to generate insightful charts and dashboards. +- Additional resources will be required to maintain the Zenoh router and InfluxDB setup. + +## Alternatives Considered +- Using a different message broker or database backend, but Zenoh and InfluxDB were chosen for their performance and compatibility with our requirements. diff --git a/docs/architecture/decisions/0004-vss-model.md b/docs/architecture/decisions/0004-vss-model.md new file mode 100644 index 0000000..42b5525 --- /dev/null +++ b/docs/architecture/decisions/0004-vss-model.md @@ -0,0 +1,24 @@ +# ADR 0004: Use VSS Convention for Syntax Naming + +## Context +To ensure consistency and clarity in our codebase, we need a standardized naming convention for syntax. + +## Decision +We have decided to adopt the Vehicle Signal Specification (VSS) convention for syntax naming. + +## Consequences +- **Pros**: + - Promotes uniformity across the project. + - Aligns with industry standards. + - Simplifies collaboration and onboarding. + +- **Cons**: + - Requires team members to familiarize themselves with VSS. + - Potential refactoring of existing code to comply with the convention. + +## Status +Accepted. + +## References +- [VSS Specification Documentation](https://github.com/COVESA/vss) +- [VSS Jetson Nano Documentation] (JetsonNano/vss) \ No newline at end of file diff --git a/docs/architecture/decisions/0005-can-communication-between-jetson-and-rasp.md b/docs/architecture/decisions/0005-can-communication-between-jetson-and-rasp.md new file mode 100644 index 0000000..aaa5893 --- /dev/null +++ b/docs/architecture/decisions/0005-can-communication-between-jetson-and-rasp.md @@ -0,0 +1,31 @@ +# ADR 0005: CAN Communication Between Jetson Nano and Raspberry Pi + +## Context +To ensure effective and reliable communication between the Jetson Nano and Raspberry Pi in our system, we need a robust communication protocol. CAN (Controller Area Network) is a well-established protocol designed for reliable communication in embedded systems, especially in environments with potential electrical noise. + +## Decision +We have decided to use CAN communication as the primary method for data exchange between the Jetson Nano and Raspberry Pi. + +## Rationale +- **Reliability**: CAN is designed for high-reliability communication in embedded systems. +- **Noise Resistance**: CAN is robust against electrical noise, making it suitable for our environment. +- **Scalability**: CAN allows for easy addition of other devices to the network in the future. +- **Real-Time Communication**: CAN supports real-time data exchange, which is critical for our application. + +## Consequences +- **Positive**: + - Improved communication reliability and robustness. + - Simplified integration of additional devices if needed. +- **Negative**: + - Additional hardware (CAN transceivers) are required. + +## Alternatives Considered +- **Ethernet/Wi-Fi**: These options were considered but were overkill for the simplicity and real-time requirements of our system. + +## Implementation +- Use CAN transceivers to enable communication between the Jetson Nano and Raspberry Pi. +- Configure the CAN bus with appropriate baud rates and termination resistors. +- Develop software drivers or use existing libraries to handle CAN communication. + +## Status +Accepted \ No newline at end of file diff --git a/docs/architecture/decisions/0011-qt-crosscompilation.md b/docs/architecture/decisions/0011-qt-crosscompilation.md new file mode 100644 index 0000000..0ba5180 --- /dev/null +++ b/docs/architecture/decisions/0011-qt-crosscompilation.md @@ -0,0 +1,17 @@ +# ADR 0011: Cross-compilation for Instrument Cluster on Raspberry Pi + +## Status +Accepted + +## Context +The Instrument Cluster application must run on a Raspberry Pi (ARM64), while development occurs on x86_64 environments. Direct compilation is not feasible due to architecture mismatch. + +## Decision +We decided to adopt cross-compilation using Docker with `buildx` to build ARM64 binaries from x86_64 environments. This approach allows developers to build and prepare deployable artifacts without needing ARM hardware. + +## Consequences +- Enables faster and platform-independent builds. +- Requires maintaining a custom Docker image with the necessary build tools. +- Developers must ensure correct environment configuration (e.g., credentials, SSH access). + +Implementation details and operational steps are documented in the [project deployment guide in README file](RaspberryPi/README.md). diff --git a/docs/architecture/decisions/0013-zenoh-with-shared-memory.md b/docs/architecture/decisions/0013-zenoh-with-shared-memory.md new file mode 100644 index 0000000..7f4fd98 --- /dev/null +++ b/docs/architecture/decisions/0013-zenoh-with-shared-memory.md @@ -0,0 +1,34 @@ +# ADR 0013: Use of Zenoh with Shared Memory for Intra-Host Communication + +## Status +Accepted + +## Context +Our system uses Zenoh as a data-centric communication layer for real-time data exchange between distributed components. Many of these components are co-located on the same physical machine, particularly in edge computing and robotics scenarios. + +Traditional communication methods (e.g., TCP or UDP over loopback) introduce unnecessary serialization, copying, and latency when processes are on the same host. To improve performance, Zenoh supports shared memory transport for intra-host communication. + +One of the main scenarios where this is applied is on the **Raspberry Pi**, where: +- The **middleware** component publishes CAN bus values using Zenoh +- The **Qt application** running on the same device subscribes to these values + +Using shared memory in this case improves responsiveness and reduces system resource usage, which is crucial on resource-constrained hardware like the Raspberry Pi. + +## Decision +We decided to enable and use **Zenoh with shared memory transport** for communication between local components running on the same host. + +This approach allows Zenoh participants (publishers and subscribers) to exchange data via shared memory, reducing latency and CPU overhead. + +## Consequences +### Positive +- Significantly reduced latency for intra-host communication +- Lower CPU and memory usage due to zero-copy semantics +- Improved throughput for high-frequency data streams +- Better performance on resource-constrained devices (e.g., Raspberry Pi) + +### Negative / Considerations +- Debugging shared memory issues can be more complex +- Fallback mechanisms should be in place if shared memory is not available + +## Related +- Zenoh documentation: https://zenoh.io/docs \ No newline at end of file diff --git a/docs/architecture/decisions/0013-levels-of-driving-automation.md b/docs/architecture/decisions/0014-levels-of-driving-automation.md similarity index 100% rename from docs/architecture/decisions/0013-levels-of-driving-automation.md rename to docs/architecture/decisions/0014-levels-of-driving-automation.md diff --git a/docs/architecture/decisions/DoxAdrIndex.md b/docs/architecture/decisions/DoxAdrIndex.md index 8cd5554..8a29b51 100644 --- a/docs/architecture/decisions/DoxAdrIndex.md +++ b/docs/architecture/decisions/DoxAdrIndex.md @@ -14,4 +14,4 @@ Team decisions are registered and organized here by date order: * @subpage architecture_decisions10 * @subpage architecture_decisions11 * @subpage architecture_decisions12 - +* @subpage architecture_decisions13