public class

VehicleManager

extends Service
implements DataPipeline.Operator
java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ com.openxc.VehicleManager

Class Overview

The VehicleManager is an in-process Android service and the primary entry point into the OpenXC library. An OpenXC application should bind to this service and request vehicle measurements through it either synchronously or asynchronously. The service will shut down when no more clients are bound to it. Synchronous measurements are obtained by passing the type of the desired measurement to the get(Class) method. Asynchronous measurements are obtained by defining a Measurement.Listener or VehicleMessage.Listener object and passing it to the service via the addListener method. There are three major components in the VehicleManager: VehicleDataSource, VehicleDataSink and VehicleInterface. The instance of a VehicleInterface is perhaps the most important. This represents the actual physical connection to the vehicle, and is bi-directional - it can both provide data to an application and send data back to the vehicle. In most cases, this should not be instantiated by applications; the setVehicleInterface(Class, String) method takes enough metadata for the remote VehicleService to instantiate the interface in a remote process. That way a single USB or Bluetooth connection can be shared among many applications. The VehicleManager also supports custom user-defined data sources, which can be controlled with addSource(VehicleDataSource) and removeSource(VehicleDataSource) methods. Even though data sources are instantiated by the application, their data is still shared among all OpenXC applications using the same remove process VehicleService In addition to applications registered to receive updates as a Measurement or VehicleMessage listener, the VehicleManager supports custom data sinks (e.g. FileRecorderSink) that be controlled with the addSink(VehicleDataSink) and removeSink(VehicleDataSink) methods. When a message is received from a VehicleDataSource, it is passed to every active VehicleDataSink. There will always be at least one sink that stores the latest messages and handles passing on data to users of this service.

Summary

Nested Classes
class VehicleManager.VehicleBinder Binder to connect IBinder in a ServiceConnection with the VehicleManager. 
Constants
String VEHICLE_LOCATION_PROVIDER
[Expand]
Inherited Constants
From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2
Public Constructors
VehicleManager()
Public Methods
void addListener(Class<? extends Measurement> measurementType, Measurement.Listener listener)
Register to receive asynchronous updates for a specific Measurement type.
void addListener(Class<? extends VehicleMessage> messageType, VehicleMessage.Listener listener)
Register to receive asynchronous updates for a specific VehicleMessage type.
void addListener(KeyedMessage keyedMessage, VehicleMessage.Listener listener)
Register to receive a callback when a message with same key as the given KeyedMessage is received.
void addListener(KeyMatcher matcher, VehicleMessage.Listener listener)
Register to receive a callback when a message with key matching the given KeyMatcher is received.
void addListener(MessageKey key, VehicleMessage.Listener listener)
Register to receive a callback when a message with the given key is received.
void addOnVehicleInterfaceConnectedListener(ViConnectionListener listener)
Register a listener to receive a callback when the selected VI is connected.
void addSink(VehicleDataSink sink)
Add a new data sink to the vehicle service.
void addSource(VehicleDataSource source)
Add a new data source to the vehicle service.
VehicleMessage get(MessageKey key)
Retrieve the most current value of a keyed message.
Measurement get(Class<? extends Measurement> measurementType)
Retrieve the most current value of a measurement.
VehicleInterfaceDescriptor getActiveVehicleInterface()
Returns a descriptor of the active vehicle interface.
int getMessageCount()
Read the number of messages received by the vehicle service.
String getVehicleInterfaceDeviceId()
Query for the unique device ID of the active VI.
String getVehicleInterfaceVersion()
Query for the firmware version of the active VI.
boolean isViConnected()
Return the connection status of the selected VI.
IBinder onBind(Intent intent)
void onCreate()
void onDestroy()
void onPipelineActivated()
void onPipelineDeactivated()
boolean onUnbind(Intent intent)
void removeListener(KeyedMessage message, VehicleMessage.Listener listener)
Unregister a previously registered keyed message listener.
void removeListener(KeyMatcher matcher, VehicleMessage.Listener listener)
Unregister a previously registered key matcher listener.
void removeListener(Class<? extends VehicleMessage> messageType, VehicleMessage.Listener listener)
Unregister a previously registered message type listener.
void removeListener(MessageKey key, VehicleMessage.Listener listener)
Unregister a previously registered key listener.
void removeListener(Class<? extends Measurement> measurementType, Measurement.Listener listener)
Unregister a previously registered Measurement.Listener instance.
void removeSink(VehicleDataSink sink)
Remove a previously registered sink from the data pipeline.
void removeSource(VehicleDataSource source)
Remove a previously registered source from the data pipeline.
VehicleMessage request(KeyedMessage message)
Send a message to the VehicleInterface and wait up to 2 seconds to receive a response.
void request(KeyedMessage message, VehicleMessage.Listener listener)
Send a message to the VehicleInterface and register the given listener to receive the first response matching the message's key.
String requestCommandMessage(Command.CommandType type)
Send a command request to the vehicle that does not require any metadata.
boolean send(Measurement message)
Convert a Measurement to a SimpleVehicleMessage and send it through the active VehicleInterface.
boolean send(VehicleMessage message)
Send a message to the vehicle through the active VehicleInterface without waiting for a response.
void setBluetoothPollingStatus(boolean enabled)
Control whether polling is used to connect to a Bluetooth device or not.
void setNativeGpsStatus(boolean enabled)
Control whether the device's built-in GPS is used to provide location.
void setVehicleInterface(Class<? extends VehicleInterface> vehicleInterfaceType)
Change the active vehicle interface to a new type using its default resource identifier.
void setVehicleInterface(Class<? extends VehicleInterface> vehicleInterfaceType, String resource)
Change the active vehicle interface to a new type using the given resource.
String toString()
void waitUntilBound()
Block until the VehicleManager is alive and can return measurements.
[Expand]
Inherited Methods
From class android.app.Service
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks
From interface android.content.ComponentCallbacks2
From interface com.openxc.DataPipeline.Operator

Constants

public static final String VEHICLE_LOCATION_PROVIDER

Constant Value: "vehicle"

Public Constructors

public VehicleManager ()

Public Methods

public void addListener (Class<? extends Measurement> measurementType, Measurement.Listener listener)

Register to receive asynchronous updates for a specific Measurement type. A Measurement is a specific, known VehicleMessage subtype. Use this method to register an object implementing the Measurement.Listener interface to receive real-time updates whenever a new value is received for the specified measurementType. Make sure you unregister your listeners with VehicleManager.removeListener(...) when your activity or service closes and no longer requires updates.

Parameters
measurementType The class of the Measurement (e.g. VehicleSpeed.class) the listener was listening for
listener An listener instance to receive the callback.

public void addListener (Class<? extends VehicleMessage> messageType, VehicleMessage.Listener listener)

Register to receive asynchronous updates for a specific VehicleMessage type. Use this method to register an object implementing the VehicleMessage.Listener interface to receive real-time updates whenever a new value is received for the specified message type. Make sure you unregister your listeners with VehicleManager.removeListener(...) when your activity or service closes and no longer requires updates.

Parameters
messageType The class of the VehicleMessage (e.g. SimpleVehicleMessage.class) the listener is listening for
listener An listener instance to receive the callback.

public void addListener (KeyedMessage keyedMessage, VehicleMessage.Listener listener)

Register to receive a callback when a message with same key as the given KeyedMessage is received.

Parameters
keyedMessage A message with the key you want to receive updates for - the response to a command typically has the same key as the request, so you can use the outgoing message's KeyedMessage to register to receive a response.
listener An listener instance to receive the callback.

public void addListener (KeyMatcher matcher, VehicleMessage.Listener listener)

Register to receive a callback when a message with key matching the given KeyMatcher is received. This function can be used to set up a wildcard listener, or one that receives a wider range of responses than just a 1 to 1 match of keys.

Parameters
matcher A KeyMatcher implement the desired filtering logic.
listener An listener instance to receive the callback.

public void addListener (MessageKey key, VehicleMessage.Listener listener)

Register to receive a callback when a message with the given key is received.

Parameters
key The key you want to receive updates.
listener An listener instance to receive the callback.

public void addOnVehicleInterfaceConnectedListener (ViConnectionListener listener)

Register a listener to receive a callback when the selected VI is connected.

Parameters
listener The listener that should receive the callback.

public void addSink (VehicleDataSink sink)

Add a new data sink to the vehicle service. A data sink added with this method will receive all new measurements as they arrive from registered data sources. For example, to use the trace file recorder sink, call the addSink method after binding with VehicleManager: service.addSink(new FileRecorderSink( new AndroidFileOpener("openxc", this)));

Parameters
sink an instance of a VehicleDataSink

public void addSource (VehicleDataSource source)

Add a new data source to the vehicle service. For example, to use the trace data source to playback a trace file, call the addSource method after binding with VehicleManager: service.addSource(new TraceVehicleDataSource( new URI("/sdcard/openxc/trace.json"))));

Parameters
source an instance of a VehicleDataSource

public VehicleMessage get (MessageKey key)

Retrieve the most current value of a keyed message.

Returns
  • An instance of the requested Measurement which may or may not have a value.
Throws
NoValueException if no value has yet been received for this measurementType
See Also

public Measurement get (Class<? extends Measurement> measurementType)

Retrieve the most current value of a measurement.

Parameters
measurementType The class of the requested Measurement (e.g. VehicleSpeed.class)
Returns
  • An instance of the requested Measurement which may or may not have a value.
Throws
UnrecognizedMeasurementTypeException if passed a measurementType that does not extend Measurement
NoValueException if no value has yet been received for this measurementType
See Also

public VehicleInterfaceDescriptor getActiveVehicleInterface ()

Returns a descriptor of the active vehicle interface.

Returns
  • A VehicleInterfaceDescriptor for the active VI or null if none is enabled.

public int getMessageCount ()

Read the number of messages received by the vehicle service.

Throws
VehicleServiceException if the listener is unable to be unregistered with the library internals - an exceptional situation that shouldn't occur.

public String getVehicleInterfaceDeviceId ()

Query for the unique device ID of the active VI.

Returns
  • the device ID string or null if not known.

public String getVehicleInterfaceVersion ()

Query for the firmware version of the active VI.

Returns
  • the firmware version string or null if not known.

public boolean isViConnected ()

Return the connection status of the selected VI.

Returns
  • true if the selected VI reports that it is connected to the vehicle.

public IBinder onBind (Intent intent)

public void onCreate ()

public void onDestroy ()

public void onPipelineActivated ()

public void onPipelineDeactivated ()

public boolean onUnbind (Intent intent)

public void removeListener (KeyedMessage message, VehicleMessage.Listener listener)

Unregister a previously registered keyed message listener.

Parameters
listener The listener to remove.

public void removeListener (KeyMatcher matcher, VehicleMessage.Listener listener)

Unregister a previously registered key matcher listener.

Parameters
listener The listener to remove.

public void removeListener (Class<? extends VehicleMessage> messageType, VehicleMessage.Listener listener)

Unregister a previously registered message type listener.

Parameters
messageType The class of the VehicleMessage this listener was registered to receive. A listener can be registered to receive multiple message types, which is why this must be specified when removing a listener.
listener The listener to remove.

public void removeListener (MessageKey key, VehicleMessage.Listener listener)

Unregister a previously registered key listener.

Parameters
listener The listener to remove.

public void removeListener (Class<? extends Measurement> measurementType, Measurement.Listener listener)

Unregister a previously registered Measurement.Listener instance. When an application is no longer interested in receiving measurement updates (e.g. when it's pausing or exiting) it should unregister all previously registered listeners to save on CPU.

Parameters
measurementType The class of the requested Measurement (e.g. VehicleSpeed.class)
listener The listener to remove.

public void removeSink (VehicleDataSink sink)

Remove a previously registered sink from the data pipeline.

public void removeSource (VehicleDataSource source)

Remove a previously registered source from the data pipeline.

public VehicleMessage request (KeyedMessage message)

Send a message to the VehicleInterface and wait up to 2 seconds to receive a response. This is a blocking version of the other request(...) method.

Returns
  • The response if one is received before the timeout, otherwise null.

public void request (KeyedMessage message, VehicleMessage.Listener listener)

Send a message to the VehicleInterface and register the given listener to receive the first response matching the message's key. This function is non-blocking. The listener is unregistered after the first response is received. If you need to accept multiple responses for the same request, you must manually register your own listener to control its lifecycle.

Parameters
message The desired message to send to the vehicle.
listener The message listener that should receive a callback when a response matching the outgoing message's key is received from the VI.

public String requestCommandMessage (Command.CommandType type)

Send a command request to the vehicle that does not require any metadata.

Parameters
type The command request type to send to the VI.
Returns
  • The message returned by the VI in response to this command or null if none was received.

public boolean send (Measurement message)

Convert a Measurement to a SimpleVehicleMessage and send it through the active VehicleInterface.

Parameters
message The desired message to send to the vehicle.
Returns
  • true if the message was sent successfully on an interface.

public boolean send (VehicleMessage message)

Send a message to the vehicle through the active VehicleInterface without waiting for a response.

Parameters
message The desired message to send to the vehicle.
Returns
  • true if the message was sent successfully on an interface.

public void setBluetoothPollingStatus (boolean enabled)

Control whether polling is used to connect to a Bluetooth device or not.

Parameters
enabled True if polling should be used to connect to a Bluetooth device.

public void setNativeGpsStatus (boolean enabled)

Control whether the device's built-in GPS is used to provide location.

Parameters
enabled True if GPS should be read from the Android device and injected as vehicle data whenever a vehicle interface is connected.

public void setVehicleInterface (Class<? extends VehicleInterface> vehicleInterfaceType)

Change the active vehicle interface to a new type using its default resource identifier. To disable all vehicle interfaces, pass null to this function.

Parameters
vehicleInterfaceType the VI type to activate or null to disable all VIs.

public void setVehicleInterface (Class<? extends VehicleInterface> vehicleInterfaceType, String resource)

Change the active vehicle interface to a new type using the given resource. To disable all vehicle interfaces, pass null to this function. The only valid VehicleInteface types are those included with the library - the vehicle service running in a remote process is the one to actually instantiate the interfaces. Interfaces added with this method will be available for all other OpenXC applications running in the system.

Parameters
vehicleInterfaceType A class implementing VehicleInterface that is included in the OpenXC library
resource A descriptor or a resource necessary to initialize the interface. See the specific implementation of VehicleService to find the required format of this parameter.

public String toString ()

public void waitUntilBound ()

Block until the VehicleManager is alive and can return measurements. Most applications don't need this and don't wait this method, but it can be useful for testing when you need to make sure you will get a measurement back from the system.