Automotive Message Broker DBus API Documentation

Version

0.13

Back to AMB Documentation Main

Introduction

AMB organizes the API into two general interface categories. First the Manager interface (see manager.txt) which includes tools for using the other interfaces. Second is a number of interfaces that represent vehicle data. The latter follows the schema of "org.automotive.DataType" and are contained in verious DBus paths. The DBus paths are generally organized by /{source}/{zone}/DataType. "source" refers to the AMB source that produces the data. "zone" refers to the zone in which the data type is located in the vehicle or "0" for no zone.

The interfaces and data types are documented in amb.fidl. Franca IDL tools can be used to generate DBus introspection xml which can be used to generate bindings for your language of choice. These interfaces types map to internal AMB properties. To understand the mappings, see the mapping documentation

Basic Recommended Usage

It is recommended that the Manager interface be used to find the DBus Object that contains the data type you need. This is done through the FindObject() call. It is expected that DBus Object Paths may change and so it is not appropriate to hard code DBus Object Paths.

Here is a pseudo-code example of how the api is to be used:

var manager = dbus.interface("org.automotive.Manager", "/");

var speedObjectPaths = manager.FindObject("VehicleSpeed");

var speedObject = dbus.interface("org.automotive.VehicleSpeed", speedObjectPaths[0]);

console.log("Vehicle Speed: " + speedObject.Speed);

Automotive Manager

Manager is a helper interface for discovering and finding available objects. Manager also helps users look up objects by zone and get additional information about a data type (ieorg.automotive.Manager.ZonesForObjectName).

Zones

'Zone' describes the position in the vehicle where the object is located. The Zone type is a bitfield of values that can be combined to describe a specific location. For example

Zone.Front | Zone.Left

(which is '9') may represent the driver position.

enumeration Zone {
  None = 0,
  Front = 1,
  Middle = 1 << 1,
  Right = 1 << 2,
  Left = 1 << 3,
  Rear = 1 << 4,
  Center = 1 << 5
}

Vehicle Property Type

Vehicle Property Type is the common interface which all Data types are derived. This interface is as follows:

interface VehiclePropertyType {
  attribute Double Time readonly
  attribute Zone Zone readonly
  method GetHistory(Double beginTime, Double endTime) {
    out{ Dictionary result}
  }
}

Data types

The data types try to conform to the [http://w3c.github.io/automotive-bg/data_spec.html W3C Automotive Business Group Vehicle Data Specification] as much as possible. There are differences in the Zone type, and this vehicle API contains some additional data types that the W3C Business Group has not yet defined. 'Time' also represents relative time in seconds rather than time in ms since epoch (DOMTimeStamp). The names of the attributes are also different because of Web vs. DBus conventions. In this Vehicle API, DBus properties use CamelCase (ie Speed vs speed) vs lowerCamelCase. Units and types are the same where possible.

Also note that many types have been marked "deprecated" and replaced with the W3C version of the type. Deprecated types should not be used in new projects.