Skip to content

Commit c8df463

Browse files
jankubovyjankubovy
committed
VSS to VHAL mapper.
Signed-off-by: Jan Kubovy <jan.kubovy@bmw.de>
1 parent 7ec87b0 commit c8df463

File tree

10 files changed

+19190
-0
lines changed

10 files changed

+19190
-0
lines changed

‎docs/vhal.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# VHAL Exporter
2+
3+
The VHAL exporter maps the VSS tree to Android VHAL properties by creating or modifying given map file and generating
4+
needed Java and AIDL sources.
5+
6+
The Android VHAL property ID is composed of 4 parts (0xGATTDDDD):
7+
8+
- [Group](https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehiclePropertyGroup.aidl): 1 nibble
9+
- [Area](https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleArea.aidl): 1 nibble
10+
- [Type](https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehiclePropertyType.aidl): 1 byte
11+
- iDentifier: 2 bytes - as sequence (max 65535)
12+
13+
This mapper can create all group of properties defined in
14+
[VehiclePropertyGroup](https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehiclePropertyGroup.aidl)
15+
and one additional we call VSS to demonstrate the possibility of a VSS specific scope (group).
16+
17+
## Property Change Mode
18+
19+
Each VHAL property has one of the following change modes:
20+
21+
STATIC
22+
: used to VSS node types ATTRIBUTE and ACTUATOR.
23+
24+
ON_CHANGE
25+
: used for VSS node type SENSOR.
26+
27+
CONTINUOUS
28+
: used for VSS node type SENSOR if the path of that VSS node is present in JSON file provided by `--continuous-change-mode`.
29+
30+
### Continuous Change Mode List Example
31+
32+
`vss_continuous.json`:
33+
```json
34+
[
35+
"Vehicle.Speed",
36+
"Vehicle.TraveledDistance",
37+
"Vehicle.Powertrain.Range",
38+
"Vehicle.Powertrain.CombustionEngine.Speed",
39+
"Vehicle.OBD.EngineSpeed",
40+
"Vehicle.Powertrain.ElectricMotor.Speed",
41+
"Vehicle.Powertrain.CombustionEngine.EOT",
42+
"Vehicle.Powertrain.CombustionEngine.EngineOil.Temperature",
43+
"Vehicle.Powertrain.TractionBattery.StateOfCharge.CurrentEnergy",
44+
"Vehicle.Powertrain.FuelSystem.AbsoluteLevel",
45+
"Vehicle.Chassis.Axle.Row1.SteeringAngle",
46+
"Vehicle.Chassis.Axle.Row2.SteeringAngle",
47+
"Vehicle.Exterior.AirTemperature",
48+
"Vehicle.Powertrain.CombustionEngine.ECT",
49+
"Vehicle.Powertrain.CombustionEngine.EngineCoolant.Temperature",
50+
"Vehicle.Powertrain.ElectricMotor.CoolantTemperature",
51+
"Vehicle.Powertrain.ElectricMotor.EngineCoolant.Temperature",
52+
"Vehicle.Powertrain.TractionBattery.StateOfCharge.Current",
53+
"Vehicle.Powertrain.TractionBattery.StateOfCharge.Displayed",
54+
"Vehicle.Powertrain.TractionBattery.Charging.ChargeCurrent.DC",
55+
"Vehicle.Powertrain.TractionBattery.Charging.ChargeCurrent.Phase1",
56+
"Vehicle.Powertrain.TractionBattery.Charging.ChargeCurrent.Phase2",
57+
"Vehicle.Powertrain.TractionBattery.Charging.ChargeCurrent.Phase3",
58+
"Vehicle.Powertrain.TractionBattery.Charging.ChargeVoltage.DC",
59+
"Vehicle.Powertrain.TractionBattery.Charging.ChargeVoltage.Phase1",
60+
"Vehicle.Powertrain.TractionBattery.Charging.ChargeVoltage.Phase2",
61+
"Vehicle.Powertrain.TractionBattery.Charging.ChargeVoltage.Phase3",
62+
"Vehicle.Powertrain.TractionBattery.Charging.ChargeRate",
63+
"Vehicle.Powertrain.TractionBattery.Charging.TimeToComplete",
64+
"Vehicle.Powertrain.TractionBattery.Temperature.Average",
65+
"Vehicle.Chassis.Axle.Row1.Wheel.Left.Tire.Pressure",
66+
"Vehicle.Chassis.Axle.Row1.Wheel.Right.Tire.Pressure",
67+
"Vehicle.Chassis.Axle.Row2.Wheel.Left.Tire.Pressure",
68+
"Vehicle.Chassis.Axle.Row2.Wheel.Right.Tire.Pressure"
69+
]
70+
```
71+
72+
## Examples
73+
74+
To generate SYSTEM properties use the following command. With SYSTEM properties we need to make sure not to conflict
75+
with existing ones in the platform, therefore the use of `--min-property-id` is needed when generating the map file
76+
for the first time:
77+
78+
```bash
79+
vspec export jsonvhal \
80+
--vspec /path/to/vehicle_signal_specification/spec/VehicleSignalSpecification.vspec \
81+
--min-property-id 32768 \
82+
--vhal-map vss_to_android_property_map.json \
83+
--continuous-change-mode vss_continuous.json \
84+
--output-dir /path/to/output
85+
```
86+
87+
To only update SYSTEM properties, i.e. ignore all newly added VSS nodes to the spec add `--no-extend-new` argument:
88+
89+
```bash
90+
vspec export jsonvhal \
91+
--vspec /path/to/vehicle_signal_specification/spec/VehicleSignalSpecification.vspec \
92+
--vhal-map vss_to_android_property_map.json \
93+
--continuous-change-mode vss_continuous.json \
94+
--output-dir /path/to/output \
95+
--no-extend-new
96+
```
97+
98+
To generate VENDOR properties use the argument `--property-group 2`:
99+
100+
```bash
101+
vspec export jsonvhal \
102+
--vspec /path/to/vehicle_signal_specification/spec/VehicleSignalSpecification.vspec \
103+
--property-group 2 \
104+
--vhal-map vss_to_android_property_map.json \
105+
--continuous-change-mode vss_continuous.json \
106+
--output-dir /path/to/output
107+
```
108+
109+
To generate VHAL properties in custom VSS group use the argument `--property-group 4`:
110+
111+
```bash
112+
vspec export jsonvhal \
113+
--vspec /path/to/vehicle_signal_specification/spec/VehicleSignalSpecification.vspec \
114+
--property-group 4 \
115+
--vhal-map vss_to_android_property_map.json \
116+
--continuous-list-change-mode vss_continuous.json \
117+
--output-dir /path/to/output/
118+
```

‎src/vss_tools/cli.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ def cli(ctx: click.Context, log_level: str, log_file: Path):
4949
"tree": "vss_tools.exporters.tree:cli",
5050
"samm": "vss_tools.exporters.samm:cli",
5151
"go": "vss_tools.exporters.go:cli",
52+
"vhal": "vss_tools.exporters.vhal:cli",
5253
},
5354
)
5455
@click.pass_context

‎src/vss_tools/cli_options.py‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,3 +158,72 @@ def validate_attribute(value):
158158
)
159159

160160
pretty_print_opt = option("--pretty/--no-pretty", help="Pretty print.", default=False, show_default=True)
161+
162+
vhal_map_opt = option(
163+
"--vhal-map",
164+
type=click.Path(dir_okay=False, readable=True, path_type=Path, exists=False),
165+
required=True,
166+
help="""
167+
Read a json file with mapping of VSS property names to Android vehicle property ids.
168+
The file containing json list of all VSS properties (leaves) mappings by vss_tools generated VHAL IDs.
169+
""",
170+
)
171+
172+
continuous_change_mode_opt = option(
173+
"--continuous-change-mode",
174+
type=click.Path(dir_okay=False, readable=True, path_type=Path, exists=True),
175+
required=False,
176+
help="Read a json file list of VSS paths which should be considered as continuous change mode.",
177+
)
178+
179+
output_dir_opt = option(
180+
"--output-dir",
181+
type=click.Path(dir_okay=True, readable=True, path_type=Path, exists=True),
182+
required=True,
183+
help="Output directory, where vhal specific generated files are saved into.",
184+
)
185+
186+
property_group_opt = option(
187+
"--property-group",
188+
type=int,
189+
required=False,
190+
default=1,
191+
show_default=True,
192+
help="""
193+
Group of generated VHAL properties: 1 = SYSTEM, 2 = VENDOR, 3 = BACKPORTED, 4 = VSS.
194+
See https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehiclePropertyGroup.aidl
195+
""",
196+
)
197+
198+
min_property_id_opt = option(
199+
"--min-property-id",
200+
type=int,
201+
required=False,
202+
default=1,
203+
show_default=True,
204+
help="Stating ID for newly generated properties. This considers only the last 2 bytes of the VHAL property ID.",
205+
)
206+
207+
extend_new_opt = option(
208+
"--extend-new/--no-extend-new",
209+
help="""
210+
Whether to extend the map with new VSS nodes from the spec not present in the map file or only update
211+
existing VHAL properties and ignores all new VSS nodes.
212+
""",
213+
default=True,
214+
show_default=True,
215+
)
216+
217+
override_vhal_units_opt = option(
218+
"--override-vhal-units/--no-override-vhal-units",
219+
help="Overrides previously generated VHAL units.",
220+
default=False,
221+
show_default=True,
222+
)
223+
224+
override_vhal_datatype_opt = option(
225+
"--override-vhal-datatype/--no-override-vhal-datatype",
226+
help="Overrides previously generated VHAL datatypes.",
227+
default=False,
228+
show_default=True,
229+
)

‎src/vss_tools/exporters/vhal.py‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Copyright (c) 2025 Contributors to COVESA
2+
#
3+
# This program and the accompanying materials are made available under the
4+
# terms of the Mozilla Public License 2.0 which is available at
5+
# https://www.mozilla.org/en-US/MPL/2.0/
6+
#
7+
# SPDX-License-Identifier: MPL-2.0
8+
9+
from pathlib import Path
10+
11+
import rich_click as click
12+
13+
import vss_tools.cli_options as clo
14+
from vss_tools import log
15+
from vss_tools.main import get_trees
16+
from vss_tools.utils.vhal.vhal_mapper import VhalMapper
17+
18+
19+
@click.command()
20+
@clo.vspec_opt
21+
@clo.vhal_map_opt
22+
@clo.continuous_change_mode_opt
23+
@clo.output_dir_opt
24+
@clo.extend_new_opt
25+
@clo.property_group_opt
26+
@clo.min_property_id_opt
27+
@clo.override_vhal_units_opt
28+
@clo.override_vhal_datatype_opt
29+
def cli(
30+
vspec: Path,
31+
vhal_map: Path,
32+
continuous_change_mode: Path | None,
33+
output_dir: Path,
34+
extend_new: bool,
35+
property_group: int,
36+
min_property_id: int,
37+
override_vhal_units: bool,
38+
override_vhal_datatype: bool,
39+
):
40+
"""
41+
Export as VSS as VHAL mapping file, Java and AIDL sources.
42+
"""
43+
tree, datatype_tree = get_trees(
44+
vspec=vspec,
45+
include_dirs=(),
46+
aborts=(),
47+
strict=False,
48+
extended_attributes=(),
49+
quantities=(),
50+
units=(),
51+
types=(),
52+
overlays=(),
53+
expand=True,
54+
)
55+
56+
log.info("Generating JSON output for VHAL Mapper...")
57+
mapper = VhalMapper(
58+
group=property_group,
59+
include_new=extend_new,
60+
starting_id=min_property_id,
61+
override_units=override_vhal_units,
62+
override_datatype=override_vhal_datatype,
63+
)
64+
65+
if continuous_change_mode is not None:
66+
mapper.load_continuous_list(continuous_change_mode)
67+
mapper.load(vhal_map, tree)
68+
mapper.safe(vhal_map)
69+
70+
java_output = output_dir / "VehiclePropertyIdsVss.java"
71+
permissions_output = output_dir / "VssPermissions.java"
72+
mapper.generate_java_files(java_output, permissions_output)
73+
74+
aidl_output = output_dir / "VehiclePropertyVss.aidl"
75+
mapper.generate_aidl_file(aidl_output)

‎src/vss_tools/utils/vhal/__init__.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Copyright (c) 2025 Contributors to COVESA
2+
#
3+
# This program and the accompanying materials are made available under the
4+
# terms of the Mozilla Public License 2.0 which is available at
5+
# https://www.mozilla.org/en-US/MPL/2.0/
6+
#
7+
# SPDX-License-Identifier: MPL-2.0

0 commit comments

Comments
 (0)