Skip to content

Commit 14ae808

Browse files
committed
refactor examples structure
- alias existing examples in `/examples` - add README
1 parent ce6983f commit 14ae808

File tree

4 files changed

+170
-1
lines changed

4 files changed

+170
-1
lines changed

README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ communication/
120120
### For Users
121121
- [User Guide](score/mw/com/README.md) - Getting started with the API
122122
- [API Reference](score/mw/com/design/README.md) - Detailed API documentation
123-
- [Examples](score/mw/com/example/) - Code examples and tutorials
123+
- [Examples](examples/) - Code examples and tutorials
124124

125125
### For Developers
126126
- [Architecture Guide](score/mw/com/design/README.md) - System architecture overview

examples/BUILD

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# *******************************************************************************
2+
# Copyright (c) 2026 Contributors to the Eclipse Foundation
3+
#
4+
# See the NOTICE file(s) distributed with this work for additional
5+
# information regarding copyright ownership.
6+
#
7+
# This program and the accompanying materials are made available under the
8+
# terms of the Apache License Version 2.0 which is available at
9+
# https://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# SPDX-License-Identifier: Apache-2.0
12+
# *******************************************************************************
13+
14+
alias(
15+
name = "com_api_example",
16+
actual = "//score/mw/com/example/com-api-example:com-api-example",
17+
visibility = ["public"],
18+
)
19+
20+
alias(
21+
name = "ipc_bridge_cpp",
22+
actual = "//score/mw/com/example/ipc_bridge:ipc_bridge_cpp",
23+
visibility = ["public"],
24+
)
25+
26+
alias(
27+
name = "ipc_bridge_rs",
28+
actual = "//score/mw/com/example/ipc_bridge:ipc_bridge_rs",
29+
visibility = ["public"],
30+
)

examples/README.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Examples
2+
3+
This directory contains aliases to example applications demonstrating the S-CORE Communication middleware API.
4+
5+
## Available Examples
6+
7+
- **[COM-API-Example](#com-api-example)**: Rust-based producer-consumer pattern demonstrating the Communication API with tire pressure data
8+
- **[IPC Bridge](#ipc-bridge)**: C++/Rust application demonstrating IPC communication with skeleton/proxy pattern
9+
10+
## COM-API-Example
11+
12+
### Standard Build (Host Platform)
13+
14+
```bash
15+
bazel build //examples/com-api-example:com-api-example
16+
```
17+
18+
### QNX Cross-Compilation
19+
20+
```bash
21+
bazel build --config=x86_64-qnx //examples/com-api-example:com-api-example
22+
```
23+
24+
### Running
25+
26+
After building, the binary will be in `bazel-bin/score/mw/com/example/com-api-example/com-api-example`.
27+
28+
### Quick Start
29+
30+
To see the COM API in action, run the example from the repo root:
31+
32+
```bash
33+
./bazel-bin/score/mw/com/example/com-api-example/com-api-example
34+
```
35+
36+
The application demonstrates a producer-consumer pattern where:
37+
38+
- A `VehicleOfferedProducer` publishes tire pressure data
39+
- A `VehicleConsumer` subscribes to and receives tire pressure updates
40+
- Five samples are sent with incrementing tire pressure values (5.0, 6.0, 7.0, 8.0, 9.0)
41+
- Each sample is read back and validated
42+
43+
You should see output showing tire data being sent and received, demonstrating the complete publish-subscribe workflow.
44+
45+
### Code Structure
46+
47+
The example demonstrates several key patterns:
48+
49+
### VehicleMonitor Struct
50+
51+
A composite structure that combines:
52+
53+
- `VehicleConsumer`: Subscribes to vehicle data
54+
- `VehicleOfferedProducer`: Publishes vehicle data
55+
- `Subscription`: Active subscription to tire data
56+
57+
### Producer-Consumer Pattern
58+
59+
```rust
60+
// Create producer
61+
let producer = create_producer(runtime, service_id.clone());
62+
63+
// Create consumer
64+
let consumer = create_consumer(runtime, service_id);
65+
66+
// Create monitor combining both
67+
let monitor = VehicleMonitor::new(consumer, producer).unwrap();
68+
69+
// Write data
70+
monitor.write_tire_data(Tire { pressure: 5.0 }).unwrap();
71+
72+
// Read data
73+
let tire_data = monitor.read_tire_data().unwrap();
74+
```
75+
76+
## IPC Bridge
77+
78+
### Standard Build (Host Platform)
79+
80+
```bash
81+
bazel build //examples:ipc_bridge_cpp
82+
```
83+
84+
### QNX Cross-Compilation
85+
86+
```bash
87+
bazel build --config=x86_64-qnx //examples:ipc_bridge_cpp
88+
```
89+
90+
### Running
91+
92+
After building the binary will be in `bazel-bin/score/mw/com/example/ipc_bridge/ipc_bridge_cpp`.
93+
94+
#### Quick Start (Two Terminals)
95+
96+
To see the IPC communication in action, open two terminals in the repo root:
97+
98+
**Terminal 1 - Start Skeleton (Publisher):**
99+
100+
```bash
101+
./bazel-bin/score/mw/com/example/ipc_bridge/ipc_bridge_cpp \
102+
--mode skeleton \
103+
--cycle-time 1000 \
104+
--num-cycles 10 \
105+
--service_instance_manifest score/mw/com/example/ipc_bridge/etc/mw_com_config.json
106+
```
107+
108+
**Terminal 2 - Start Proxy (Subscriber):**
109+
110+
```bash
111+
./bazel-bin/score/mw/com/example/ipc_bridge/ipc_bridge_cpp \
112+
--mode proxy \
113+
--cycle-time 500 \
114+
--num-cycles 20 \
115+
--service_instance_manifest score/mw/com/example/ipc_bridge/etc/mw_com_config.json
116+
```
117+
118+
You should see the proxy discover the skeleton service, subscribe, and receive `MapApiLanesStamped` samples. The proxy validates data integrity and ordering for each received sample.
119+
120+
#### Command-Line Options
121+
122+
| Option | Description | Required |
123+
| ------ | ----------- | -------- |
124+
| `--mode, -m` | Operation mode: `skeleton`/`send` or `proxy`/`recv` | Yes |
125+
| `--cycle-time, -t` | Cycle time in milliseconds for sending/polling | Yes |
126+
| `--num-cycles, -n` | Number of cycles to execute (0 = infinite) | Yes |
127+
| `--service_instance_manifest, -s` | Path to communication config JSON | Optional |
128+
| `--disable-hash-check, -d` | Skip sample hash validation in proxy mode | Optional |
129+
130+
## Configuration
131+
132+
The communication behavior is configured via `score/mw/com/example/ipc_bridge/etc/mw_com_config.json`:
133+
134+
- Service type definitions and bindings
135+
- Event definitions with IDs
136+
- Instance-specific configuration (shared memory settings, subscriber limits)
137+
- ASIL level and process ID restrictions

score/mw/com/example/ipc_bridge/BUILD

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ cc_binary(
2424
],
2525
data = ["etc/mw_com_config.json"],
2626
features = COMPILER_WARNING_FEATURES,
27+
visibility = ["//examples:__pkg__"],
2728
deps = [
2829
":sample_sender_receiver",
2930
"//score/mw/com",
@@ -82,6 +83,7 @@ rust_binary(
8283
srcs = ["ipc_bridge.rs"],
8384
data = ["etc/mw_com_config.json"],
8485
features = ["link_std_cpp_lib"],
86+
visibility = ["//examples:__pkg__"],
8587
deps = [
8688
":ipc_bridge_gen_rs",
8789
"//score/mw/com/impl/rust:mw_com",

0 commit comments

Comments
 (0)