Skip to content
This repository was archived by the owner on Oct 6, 2025. It is now read-only.

Commit 287c023

Browse files
zilioluziliolu
authored
Merge pull request #92 from SEAME-pt/adrs-update
Add architecture decision records for VSS naming convention and cross…
2 parents 5bb0141 + 4a87aef commit 287c023

7 files changed

Lines changed: 129 additions & 1 deletion

‎docs/architecture/decisions/0003-zenoh-with-influxdb-backend.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# ADR 0003: Zenoh Router with InfluxDB Backend
2+
3+
## Status
4+
Accepted
5+
6+
## Context
7+
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.
8+
9+
## Decision
10+
We will deploy a Zenoh router running in the car, configured with an InfluxDB backend. This setup will allow:
11+
- Real-time communication between the car and the cloud.
12+
- Storage of measurement data in InfluxDB for later analysis.
13+
- Integration with Grafana to create visual dashboards for measurement data.
14+
15+
## Consequences
16+
- The Zenoh router will handle data routing efficiently, enabling seamless cloud communication.
17+
- InfluxDB will provide a reliable backend for storing time-series data.
18+
- Future integration with Grafana will allow us to generate insightful charts and dashboards.
19+
- Additional resources will be required to maintain the Zenoh router and InfluxDB setup.
20+
21+
## Alternatives Considered
22+
- Using a different message broker or database backend, but Zenoh and InfluxDB were chosen for their performance and compatibility with our requirements.

‎docs/architecture/decisions/0004-vss-model.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# ADR 0004: Use VSS Convention for Syntax Naming
2+
3+
## Context
4+
To ensure consistency and clarity in our codebase, we need a standardized naming convention for syntax.
5+
6+
## Decision
7+
We have decided to adopt the Vehicle Signal Specification (VSS) convention for syntax naming.
8+
9+
## Consequences
10+
- **Pros**:
11+
- Promotes uniformity across the project.
12+
- Aligns with industry standards.
13+
- Simplifies collaboration and onboarding.
14+
15+
- **Cons**:
16+
- Requires team members to familiarize themselves with VSS.
17+
- Potential refactoring of existing code to comply with the convention.
18+
19+
## Status
20+
Accepted.
21+
22+
## References
23+
- [VSS Specification Documentation](https://github.com/COVESA/vss)
24+
- [VSS Jetson Nano Documentation] (JetsonNano/vss)

‎docs/architecture/decisions/0005-can-communication-between-jetson-and-rasp.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# ADR 0005: CAN Communication Between Jetson Nano and Raspberry Pi
2+
3+
## Context
4+
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.
5+
6+
## Decision
7+
We have decided to use CAN communication as the primary method for data exchange between the Jetson Nano and Raspberry Pi.
8+
9+
## Rationale
10+
- **Reliability**: CAN is designed for high-reliability communication in embedded systems.
11+
- **Noise Resistance**: CAN is robust against electrical noise, making it suitable for our environment.
12+
- **Scalability**: CAN allows for easy addition of other devices to the network in the future.
13+
- **Real-Time Communication**: CAN supports real-time data exchange, which is critical for our application.
14+
15+
## Consequences
16+
- **Positive**:
17+
- Improved communication reliability and robustness.
18+
- Simplified integration of additional devices if needed.
19+
- **Negative**:
20+
- Additional hardware (CAN transceivers) are required.
21+
22+
## Alternatives Considered
23+
- **Ethernet/Wi-Fi**: These options were considered but were overkill for the simplicity and real-time requirements of our system.
24+
25+
## Implementation
26+
- Use CAN transceivers to enable communication between the Jetson Nano and Raspberry Pi.
27+
- Configure the CAN bus with appropriate baud rates and termination resistors.
28+
- Develop software drivers or use existing libraries to handle CAN communication.
29+
30+
## Status
31+
Accepted

‎docs/architecture/decisions/0011-qt-crosscompilation.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# ADR 0011: Cross-compilation for Instrument Cluster on Raspberry Pi
2+
3+
## Status
4+
Accepted
5+
6+
## Context
7+
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.
8+
9+
## Decision
10+
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.
11+
12+
## Consequences
13+
- Enables faster and platform-independent builds.
14+
- Requires maintaining a custom Docker image with the necessary build tools.
15+
- Developers must ensure correct environment configuration (e.g., credentials, SSH access).
16+
17+
Implementation details and operational steps are documented in the [project deployment guide in README file](RaspberryPi/README.md).

‎docs/architecture/decisions/0013-zenoh-with-shared-memory.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# ADR 0013: Use of Zenoh with Shared Memory for Intra-Host Communication
2+
3+
## Status
4+
Accepted
5+
6+
## Context
7+
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.
8+
9+
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.
10+
11+
One of the main scenarios where this is applied is on the **Raspberry Pi**, where:
12+
- The **middleware** component publishes CAN bus values using Zenoh
13+
- The **Qt application** running on the same device subscribes to these values
14+
15+
Using shared memory in this case improves responsiveness and reduces system resource usage, which is crucial on resource-constrained hardware like the Raspberry Pi.
16+
17+
## Decision
18+
We decided to enable and use **Zenoh with shared memory transport** for communication between local components running on the same host.
19+
20+
This approach allows Zenoh participants (publishers and subscribers) to exchange data via shared memory, reducing latency and CPU overhead.
21+
22+
## Consequences
23+
### Positive
24+
- Significantly reduced latency for intra-host communication
25+
- Lower CPU and memory usage due to zero-copy semantics
26+
- Improved throughput for high-frequency data streams
27+
- Better performance on resource-constrained devices (e.g., Raspberry Pi)
28+
29+
### Negative / Considerations
30+
- Debugging shared memory issues can be more complex
31+
- Fallback mechanisms should be in place if shared memory is not available
32+
33+
## Related
34+
- Zenoh documentation: https://zenoh.io/docs

docs/architecture/decisions/0013-levels-of-driving-automation.md renamed to docs/architecture/decisions/0014-levels-of-driving-automation.md

File renamed without changes.

‎docs/architecture/decisions/DoxAdrIndex.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,4 @@ Team decisions are registered and organized here by date order:
1414
* @subpage architecture_decisions10
1515
* @subpage architecture_decisions11
1616
* @subpage architecture_decisions12
17-
17+
* @subpage architecture_decisions13

0 commit comments

Comments
 (0)