diff options
author | Heidi von Markham <hvm@google.com> | 2016-07-27 17:37:51 +0000 |
---|---|---|
committer | android-build-merger <android-build-merger@google.com> | 2016-07-27 17:37:51 +0000 |
commit | 28386587680ee1cce48f37b62b132692e2a1626f (patch) | |
tree | 4f38c88aefb78476ff496e1b5f2dd186196d649e | |
parent | eb922462f7e05a3d967755e371109ed9ad782049 (diff) | |
parent | ac5f8e34a33c53f73b856a6fe6a16be27207716a (diff) | |
download | source.android.com-28386587680ee1cce48f37b62b132692e2a1626f.tar.gz |
Docs: Adding vehicle hal content + nav Adding KY feedback Adding Gina\'s feedback
am: ac5f8e34a3
Change-Id: I21ec62c45ff4625c6e7f568d7c426cc7e7008b60
-rw-r--r-- | src/devices/automotive.jd | 293 | ||||
-rw-r--r-- | src/devices/devices_toc.cs | 1 | ||||
-rw-r--r-- | src/devices/images/ape_fwk_hal_vehicle.png | bin | 0 -> 3546 bytes | |||
-rw-r--r-- | src/devices/images/vehicle_hal_arch.png | bin | 0 -> 29253 bytes | |||
-rw-r--r-- | src/devices/images/vehicle_hvac_get.png | bin | 0 -> 68958 bytes | |||
-rw-r--r-- | src/devices/images/vehicle_hvac_set.png | bin | 0 -> 69190 bytes |
6 files changed, 294 insertions, 0 deletions
diff --git a/src/devices/automotive.jd b/src/devices/automotive.jd new file mode 100644 index 00000000..cfcccc9d --- /dev/null +++ b/src/devices/automotive.jd @@ -0,0 +1,293 @@ +page.title=Automotive +@jd:body + +<!-- + Copyright 2016 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol id="auto-toc"> + </ol> + </div> +</div> + +<img style="float: right; margin: 0px 15px 15px 15px;" +src="images/ape_fwk_hal_vehicle.png" alt="Android vehicle HAL icon"/> + +<p>Many car subsystems interconnect with each other and the in-vehicle +infotainment (IVI) system via various bus topologies. The exact bus type and +protocols vary widely between manufacturers (and even between different vehicle +models of the same brand); examples include Controller Area Network (CAN) bus, +Local Interconnect Network (LIN) bus, Media Oriented Systems Transport (MOST), +as well as automotive-grade Ethernet and TCP/IP networks such as BroadR-Reach. +</p> +<p>Android Automotive has a hardware abstraction layer (HAL) that provides a +consistent interface to the Android framework regardless of physical transport +layer. This vehicle HAL is the interface for developing Android Automotive +implementations.</p> +<p>System integrators can implement a vehicle HAL module by connecting +function-specific platform HAL interfaces (e.g. HVAC) with technology-specific +network interfaces (e.g. CAN bus). Typical implementations may include a +dedicated Microcontroller Unit (MCU) running a proprietary real-time operating +system (RTOS) for CAN bus access or similar, which may be connected via a serial +link to the CPU running Android Automotive. Instead of a dedicated MCU, it may +also be possible to implement the bus access as a virtualized CPU. It is up to +each partner to choose the architecture suitable for the hardware as long as the +implementation fulfills the interface requirements for the vehicle HAL.</p> + +<h2 id=arch>Architecture</h2> +<p>The vehicle HAL is the interface definition between the car and the vehicle +network service:</p> + +<img src="images/vehicle_hal_arch.png" alt="Android vehicle HAL architecture"> +<p class="img-caption"><strong>Figure 1</strong>. Vehicle HAL and Android +automotive architecture</p> + +<ul> +<li><strong>Car API</strong>. Contains the APIs such as CarHvacManager, +CarSensorManager, and CarCameraManager. For details on all supported APIs, +refer to <code>/platform/packages/services/Car/car-lib</code>.</li> +<li><strong>CarService</strong>. Located at +<code>/platform/packages/services/Car/</code>.</li> +<li><strong>VehicleNetworkService</strong>. Controls vehicle HAL with built-in +security. Access restricted to system components only (non-system components +such as third party apps should use car API instead). OEMs can control access +using <code>vns_policy.xml</code> and <code>vendor_vns_policy.xml</code>. +Located at <code>/platform/packages/services/Car/vehicle_network_service/</code>; +for libraries to access the vehicle network, refer to +<code>/platform/packages/services/Car/libvehiclenetwork/</code>.</li> +<li><strong>Vehicle HAL</strong>. Interface that defines the properties OEMs can +implement and contains property metadata (for example, whether the property is +an int and which change modes are allowed). Located at +<code>hardware/libhardware/include/hardware/vehicle.h</code>. For a basic +reference implementation, refer to +<code>hardware/libhardware/modules/vehicle/</code>.</li> +</ul> + +<h2 id=prop>Vehicle properties</h2> +<p>The vehicle HAL interface is based on accessing (read, write, subscribe) a +property, which is an abstraction for a specific function. Properties can be +read-only, write-only (used to pass information to vehicle HAL level), or read +and write. Support of most properties is optional.</p> +<p>Each property is uniquely identified by an int32 key and has a predefined +type (<code>value_type</code>):</p> + +<ul> +<li><code>INT32</code> (and array), <code>INT64</code>, <code>BOOLEAN</code>, +<code>FLOAT</code> (and array), string, bytes.</li> +<li>Zoned type has zone in addition to value.</li> +</ul> + +<h3 id-=zone_type>Zone types</h3> +<p>The vehicle HAL defines three zone types:</p> +<ul> +<li><code>vehicle_zone</code>: Zone based on rows.</li> +<li><code>vehicle_seat</code>: Zone based on seats.</li> +<li><code>vehicle_window</code>: Zone based on windows.</li> +</ul> +<p>Each zoned property should use pre-defined zone type. If necessary, you can +use a custom zone type for each property (for details, see +<a href=#prop_custom>Handling custom properties</a>).</p> + +<h3 id=prop_config>Configuring a property</h3> +<p>Use <code>vehicle_prop_config_t</code> to provide configuration information +for each property. Information includes:</p> +<ul> +<li><code>access</code> (r, w, rw)</li> +<li><code>change_mode</code> (represents how property is monitored: on change vs +continuous)</li> +<li><code>min_value</code> (int32, float, int64), <code>max_value</code> (int32, +float, int64)</li> +<li><code>min_sample_rate</code>, <code>max_sample_rate</code></li> +<li><code>permission_model</code></li> +<li><code>prop</code> (Property ID, int)</li> +<li><code>value_type</code></li> +<li><code>zone_flags</code> (represents supported zones as bit flags)</li> +</ul> +<p>In addition, some properties have specific configuration flags to represent +capability.</p> + +<h2 id=interfaces>HAL interfaces</h2> +<p>The vehicle HAL uses the following interfaces:</p> +<ul> +<li><code>vehicle_prop_config_t const *(*list_properties)(..., int* +num_properties)</code>. List configuration of all properties supported by the +vehicle HAL. Only supported properties will be used by vehicle network service. +</li> +<li><code>(*get)(..., vehicle_prop_value_t *data)</code>. Read the current value +of the property. For zoned property, each zone may have different value.</li> +<li><code>(*set)(..., const vehicle_prop_value_t *data)</code>. Write a value to +property. Result of write is defined per each property.</li> +<li><code>(*subscribe)(..., int32_t prop, float sample_rate, int32_t +zones)</code>.<ul> +<li>Start monitoring property value's change. For zoned property, subscription +applies to requested zones. Zones = 0 is used to request all zones supported. +</li> +<li>Vehicle HAL should call separate callback when the property's value changes +(=on change) or in const interval (=continuous type).</ul></li> +<li><code>(*release_memory_from_get)(struct vehicle_hw_device* device, +vehicle_prop_value_t *data)</code>. Release memory allocated from get call.</ul> +</li> +</ul> + +<p>The vehicle HAL uses the following callback interfaces:</p> +<ul> +<li><code>(*vehicle_event_callback_fn)(const vehicle_prop_value_t +*event_data)</code>. Notifies vehicle property's value change. Should be done +only for subscribed properties.</li> +<li><code>(*vehicle_error_callback_fn)(int32_t error_code, int32_t property, +int32_t operation).</code> Return global vehicle HAL level error or error per +each property. Global error causes HAL restart, which can lead to restarting +other components, including applications.</li> +</ul> + +<h2 id=zone_prop>Handling zone properties</h2> +<p>A zoned property is equivalent to a collection of multiple properties where +each sub property is accessible by specified zone value.</p> +<ul> +<li><code>get</code> call for zoned property always includes zone in request, so +only the current value for the requested zone should be returned.</li> +<li><code>set</code> call for zoned property always includes zone in request, so +only the requested zone should be changed.</li> +<li><code>subscribe</code> call includes flags of all zones subscribed. Events +from un-subscribed zones should not be reported.</li> +</ul> + +<h3 id=get>Get calls</h3> +<p>During initialization, the value for the property may not be available yet as +the matching vehicle network message has not yet been received. In such cases, +the <code>get</code> call should return <code>-EAGAIN</code>. Some properties +(such as HVAC) have separate on/off power property. Calling <code>get</code> for +such a property (when powered off) should return a special value +<code>(VEHICLE_INT_OUT_OF_RANGE_OFF/VEHICLE_FLOAT_OUT_OF_RANGE_OFF)</code> +rather than returning an error.</p> +<p>In addition, some properties (such as HVAC temperature) can have a value to +indicate it is in max power mode rather than in specific temperature value. In +such cases, use special values to represent such state.</p> +<ul> +<li>VEHICLE_INT_OUT_OF_RANGE_MAX/MIN</li> +<li>VEHICLE_FLOAT_OUT_OF_RANGE_MAX/MIN</li> +</ul> + +<p>Example: get HVAC Temperature</p> +<img src="images/vehicle_hvac_get.png" alt="Vehicle HAL get HVAC example"> +<p class="img-caption"><strong>Figure 2</strong>. Get HVAC temperature (CD = +CarService, VNS = VehicleNetworkService, VHAL = Vehicle HAL)</p> + +<h3 id=set>Set calls</h3> +<p>A <code>set</code> call is an asynchronous operation involving event +notification after a requested change is made. In a typical operation, a +<code>set</code> call leads to making a change request across vehicle network. +When the change is performed by the electronic control unit (ECU) owning the +property, the updated value is returned through vehicle network and the vehicle +HAL sends an updated value as an event to vehicle network service (VNS).</p> +<p>Some <code>set</code> calls may require initial data to be ready but during +initialization, such data may not be available yet. In such cases, the +<code>set</code> call should return <code>-EAGAIN</code>. Some properties with +separate power on /off should return <code>-ESHUTDOWN</code> when the property +is powered off and set cannot be done.</p> +<p>Until <code>set</code> is made effective, <code>get</code> does not +necessarily return the same value as what is set. The exception is a property +with change mode of <code>VEHICLE_PROP_CHANGE_MODE_ON_SET.</code> This property +notifies change only when it is set by external component outside Android (for +example, clock properties such as <code>VEHICLE_PROPERTY_UNIX_TIME</code>).</p> + +<p>Example: set HVAC Temperature</p> +<img src="images/vehicle_hvac_set.png" alt="Vehicle HAL set HVAC example"> +<p class="img-caption"><strong>Figure 3</strong>. Set HVAC temperature (CD = +CarService, VNS = VehicleNetworkService, VHAL = Vehicle HAL)</p> + +<h2 id=prop_custom>Handling custom properties</h2> +<p>To support partner-specific needs, the vehicle HAL allows custom properties +that are restricted to system apps. Use the following guidelines when working +with custom properties:</p> +<ul> +<li>Key should be in [<code>VEHICLE_PROPERTY_CUSTOM_START, +VEHICLE_PROPERTY_CUSTOM_END</code>] range. Other ranges are reserved for future +extension; using such ranges can cause conflicts in future Android releases.</li> +<li>Use only defined <code>value_type</code>. BYTES type allows passing raw +data, so this is enough in most cases. Sending big data frequently through +custom properties can slow down the whole vehicle network access, so be careful +when you add a big payload.</li> +<li>Add access policy into <code>vendor_vns_policy.xml</code> (otherwise, all +access will be rejected).</li> +<li>Access via <code>VendorExtensionManager</code> (for Java components) or +via Vehicle Network Service API (for native). Do not modify other car APIs as it +can lead to compatibility issues in the future.</li> +</ul> + +<h2 id=prop_hvac>Handling HVAC properties</h2> +<p>You can use the vehicle HAL to control HVAC by setting HVAC-related +properties. Most HVAC properties are zoned properties, but a few are non-zoned +(global) properties. Example properties defined include:</p> +<ul> +<li><code>VEHICLE_PROPERTY_HVAC_TEMPERATURE_SET</code> (set temperature per each +zone).</li> +<li><code>VEHICLE_PROPERTY_HVAC_RECIRC_ON</code> (control recirculation per each +zone).</li> +</ul> +<p>For full list of HVAC properties, search for +<code>VEHICLE_PROPERTY_HVAC_*</code> in <code>vehicle.h</code>.</p> + +<h2 id=prop_sensor>Handling sensor properties</h2> +<p>Vehicle HAL sensor properties represent real sensor data or policy +information such as driving status. Some sensor information (such as driving +status and day/night mode) is accessible by any app without restriction as the +data is mandatory to build a safe vehicle application. Other sensor information +(such as vehicle speed) is more sensitive and requires specific permissions that +users can manage.</p> +<p>Supported sensor properties include:</p> +<ul> +<li><code>DRIVING_STATUS</code> (should support). Represents allowed operations +in the current driving state. This information is used to block unsafe +applications while driving.</li> +<li><code>NIGHT_MODE</code> (should support). Determines day/night mode of +display.</li> +<li><code>GEAR_SELECTION/CURRENT_GEAR</code>. Gear selected by driver vs. +actual gear.</li> +<li><code>VEHICLE_SPEED</code>. Vehicle speed. Protected with permission.</li> +<li><code>ODOMETER</code>. Current odometer reading. Protected with permission. +</li> +<li><code>FUEL_LEVEL</code>. Current fuel level in %.</li> +<li><code>FUEL_LEVEL_LOW</code>. Fuel level is low or not (boolean).</li> +</ul> + +<h2 id=security>Security</h2> +<p>The vehicle HAL supports three levels of security for accessing data:</p> +<ul> +<li>System only (controlled by <code>vns_policy.xml</code>)</li> +<li>Accessible to app with permission (through car service)</li> +<li>Accessible without permission (through car service)</li> +</ul> +<p>Direct access to vehicle properties is allowed only to selected system +components with vehicle network service acting as the gatekeeper. Most +applications go through additional gatekeeping by car service (for example, only +system applications can control HVAC as it requires system permission granted +only to system apps).</p> + +<h2 id=validation>Validation</h2> +<p>AOSP includes the following testing resources for use in development:</p> +<ul> +<li><code>hardware/libhardware/tests/vehicle/vehicle-hal-tool.c</code>. +Command-line native tool to load vehicle HAL and do simple operations. Useful +for getting the system up and running in the early stages of development.</li> +<li><code>packages/services/Car/tests/carservice_test/</code>. Contains car +service testing with mocked vehicle HAL properties. For each property, expected +behavior is implemented in the test. This can be a good starting point to +understand expected behavior.</li> +<li><code>hardware/libhardware/modules/vehicle/</code>. A basic reference +implementation.</li> +</ul> diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs index 862d6f5b..0dc2b030 100644 --- a/src/devices/devices_toc.cs +++ b/src/devices/devices_toc.cs @@ -128,6 +128,7 @@ <li><a href="<?cs var:toroot ?>devices/audio/tv.html">TV Audio</a></li> </ul> </li> + <li><a href="<?cs var:toroot ?>devices/automotive.html">Automotive</a></li> <li><a href="<?cs var:toroot ?>devices/bluetooth.html">Bluetooth</a></li> <li class="nav-section"> <div class="nav-section-header"> diff --git a/src/devices/images/ape_fwk_hal_vehicle.png b/src/devices/images/ape_fwk_hal_vehicle.png Binary files differnew file mode 100644 index 00000000..500934de --- /dev/null +++ b/src/devices/images/ape_fwk_hal_vehicle.png diff --git a/src/devices/images/vehicle_hal_arch.png b/src/devices/images/vehicle_hal_arch.png Binary files differnew file mode 100644 index 00000000..8c8a6abe --- /dev/null +++ b/src/devices/images/vehicle_hal_arch.png diff --git a/src/devices/images/vehicle_hvac_get.png b/src/devices/images/vehicle_hvac_get.png Binary files differnew file mode 100644 index 00000000..1006db69 --- /dev/null +++ b/src/devices/images/vehicle_hvac_get.png diff --git a/src/devices/images/vehicle_hvac_set.png b/src/devices/images/vehicle_hvac_set.png Binary files differnew file mode 100644 index 00000000..fcf4683b --- /dev/null +++ b/src/devices/images/vehicle_hvac_set.png |