com.digi.wva.device

Class WVA

java.lang.Object

com.digi.wva.device.WVA

public class WVA
extends Object

Configures and manages interactions with the WVA device. Most applications can use just a single WVA object to manage interactions with the WVA.

Callbacks on UI thread

To ease use of the WVA Android library, all asynchronous methods in the WVA class will by default execute their callbacks on the application UI thread (or main thread). Additionally, any "listeners" used to subscribe for data or alarms, or TCP stream connection status, will also have methods executed on the main thread by default. See the documentation for the following methods for more information on this functionality, and how to force callbacks to execute in a background thread instead, if this is useful for your application:

• WvaCallback.runsOnUiThread
• EventChannelStateListener.runsOnUiThread
• VehicleDataListener.runsOnUiThread
• FaultCodeListener.runsOnUiThread

These are some of the interactions which must be run from the main thread in Android:

• Interacting with or updating views (such as changing text, changing icons, calling notifyDataSetChanged() on an adapter, etc.)
• Creating new Toast notifications
• Manually drawing/painting on screen

The following tasks should not be done on the UI thread:

• Loading data from the network
• Performing long-running calculations
• Accessing a file or database

If the UI thread is blocked for more than a few seconds, the user may encounter an "application not responding" dialog. You should make sure to be careful in deciding which callbacks and listeners should be executed on the UI thread, and which can be handled on a background thread. (You always have the option of posting a Runnable to the main thread yourself.)

Connecting to the TCP event channel

To start the TCP event channel connection, use connectEventChannel(int, com.digi.wva.async.EventChannelStateListener) or connectEventChannel(int). (You do not need to instantiate your own EventChannel, for instance.)

Managing asynchronous event listeners

Interactions between Android's activity lifecycle and asynchronous or event-driven operations in an application can become confusing easily, especially when you need to update the UI from such callbacks. To help with this, Digi's WVA Android library is designed to allow fine-grained management of asynchronous event listeners.

In a previous release of this library, management of these listeners (such as the VehicleDataListeners associated with vehicle data subscriptions) was tightly coupled with the creation or deletion of the subscription record in the WVA itself: the only way you could set a listener was to call subscribe and pass the listener into that call, and the only way to disassociate that listener was to either call unsubscribe or another method to remove all such listeners.

By contrast, this library now gives you methods to directly set just those listeners, so that you can more easily manage your application's interactions between the event channel listeners and Android's lifecycle.

Suppose you need your application to update a line graph with new EngineSpeed values while the user is inside the app, but while the app is in the background, you only need to write those values to a database. To accomplish this, you can register a VehicleDataListener in your activity's onCreate method which will update the graph, and in onStop register another listener which will log values to the database. (You will likely want this second listener to override VehicleDataListener.runsOnUiThread() to return false, since it does not need to touch the UI.)
Compare this to the earlier design, where you would need your listener to be intrinsically aware of where data should go.

Vehicle data listeners, fault code listeners, and the event channel state listener can all be managed in this way.

Propagation of events

For both fault codes and vehicle data, there are two methods for interacting with event listeners: setVehicleDataListener(VehicleDataListener) and setVehicleDataListener(String, VehicleDataListener) for vehicle data, and similarly-named methods for fault codes. The former (taking in only a listener) will set the listener invoked on all events generated by the library, while the latter will set an additional listener to be invoked only on more specific events.

Imagine, for example, you wish to build an application which logs any and all incoming subscription vehicle data to the application logs, but also updates the application UI to display the most recent EngineSpeed value. This can be accomplished with code similar to the following:

         WVA wva = new WVA("192.168.100.1");
         int event_channel_port = 5000;

         final TextView engineSpeed = (TextView) findViewById(R.id.engineSpeed);

         // Set up listeners
         wva.setVehicleDataListener(new VehicleDataListener() {
             @Override
             public boolean runsOnUiThread() {
                 return false;
             }

             @Override
             public void onEvent(VehicleDataEvent e) {
                 Log.i("My App", "New vehicle data: " + e.getEndpoint() + " = " + e.getResponse().getValue());
             }
         });
         wva.setVehicleDataListener("EngineSpeed", new VehicleDataListener() {
             @Override
             public void onEvent(VehicleDataEvent e) {
                 engineSpeed.setText(Double.toString(e.getResponse().getValue()));
             }
         });

         // Subscribe to EngineSpeed, if necessary
         wva.subscribeToVehicleData("EngineSpeed", 10, new WvaCallback<Void>() {
             // ...
         });

         // Connect to the event channel
         wva.connectEventChannel(event_channel_port);
     

Note that this EngineSpeed listener is something you would want to control throughout the activity's lifecycle, as explained in the Managing asynchronous event listeners section above. (In fact, if your WVA object is defined globally to your application, you can set the non-specific listener once, and update the EngineSpeed listener when necessary.)

Constructor Summary

Constructors

Constructor and Description
WVA(String hostname) WVA Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
WVA	clearBasicAuth() Clears any previously-set basic authentication for HTTP or HTTPS requests.
void	configure(String configPath, JSONObject configObject, WvaCallback<Void> callback) Applies the given JSON object as configuration parameters on the specified configuration web services path.
void	configureBaudRate(int baudRate, WvaCallback<Integer> callback) Deprecated. As of version 2.0, prefer using configure(String, JSONObject, WvaCallback)
void	configurePort(int port, WvaCallback<Integer> callback) Deprecated. As of version 2.0, prefer using configure(String, JSONObject, WvaCallback)
void	connectEventChannel(int port) Convenience method for connectEventChannel(int, EventChannelStateListener), passing in null for the listener.
void	connectEventChannel(int port, EventChannelStateListener listener) Turns on the TCP stream which conveys subscription and alarm data.
void	createFaultCodeAlarm(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, int seconds, WvaCallback<Void> callback) Create an alarm for fault code data from the given ECU on the WVA.
void	createVehicleDataAlarm(String endpoint, AlarmType type, float threshold, int seconds) Calls createVehicleDataAlarm(String, AlarmType, float, int, WvaCallback) with a null callback, meaning no direct feedback as to the success or failure of the request will be available.
void	createVehicleDataAlarm(String endpoint, AlarmType type, float threshold, int seconds, WvaCallback<Void> callback) Create an alarm on the given vehicle data endpoint on the WVA.
void	deleteFaultCodeAlarm(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, WvaCallback<Void> callback) Removes the alarm on the given fault code data on the WVA, by deleting the alarm record on the device.
void	deleteVehicleDataAlarm(String endpoint, AlarmType type) Calls deleteVehicleDataAlarm(String, AlarmType, WvaCallback) with a null callback, meaning no direct feedback as to the success or failure of the request will be available.
void	deleteVehicleDataAlarm(String endpoint, AlarmType type, WvaCallback<Void> callback) Removes the alarm on the given vehicle data endpoint on the WVA, by deleting the alarm record on the device.
void	disconnectEventChannel() Disconnects from the event channel.
void	disconnectEventChannel(boolean disallowReconnect) Disconnects from the event channel conveying subscription and alarm data.
void	fetchAllEcuElementValues(String ecuName, WvaCallback<android.util.Pair<String,String>> callback) Fetches all endpoints from a single ECU, calling the provided callback's onResponse method with the data from every endpoint.
void	fetchButtonNames(WvaCallback<Set<String>> onInitialized) Asynchronously queries the WVA for the list of addressable buttons manageable by web services.
void	fetchButtonState(String buttonName, WvaCallback<Boolean> callback) Asynchronously queries the WVA for the state of the given button.
void	fetchEcuElements(String ecuName, WvaCallback<Set<String>> callback) Asynchronously queries the WVA for the list of data elements describing a specific engine control unit (ECU) in the vehicle.
void	fetchEcuElementValue(String ecuName, String element, WvaCallback<String> callback) Asynchronously queries the WVA for the value of a specific element describing a specific ECU.
void	fetchEcus(WvaCallback<Set<String>> onInitialized) Asynchronously queries the WVA for the list of addressable ECUs in the vehicle.
void	fetchFaultCode(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, WvaCallback<FaultCodeResponse> callback) Asynchronously queries the WVA for the most recent DTC report of the given type (active or inactive) on the given CAN bus.
void	fetchFaultCodeEcuNames(FaultCodes.Bus bus, WvaCallback<Set<String>> callback) Asynchronously queries the WVA for the list of ECUs that the system knows exist on the given CAN bus, since they might be providing active or inactive DTC messages.
void	fetchLedNames(WvaCallback<Set<String>> onInitialized) Asynchronously queries the WVA for the list of addressable LEDs manageable by web services.
void	fetchLedState(String ledName, WvaCallback<Boolean> callback) Asynchronously queries the WVA for the state of the given LED.
void	fetchTime(WvaCallback<DateTime> callback) Asynchronously queries the WVA for its current time.
void	fetchVehicleData(String endpoint, WvaCallback<VehicleDataResponse> callback) Asynchronously queries the WVA for the newest data at the given endpoint.
void	fetchVehicleDataEndpoints(WvaCallback<Set<String>> onInitialized) Initializes the cache of vehicle data endpoint names.
Set<String>	getCachedButtonNames() Returns the cached list of addressable buttons on the WVA.
Set<String>	getCachedEcuElements(String ecuName) Returns the library's cached list of specific ECU elements on a given ECU.
String	getCachedEcuElementValue(String ecuName, String endpoint) Synchronously returns the library's last cached value of a specific element of a specific ECU of the WVA.
Set<String>	getCachedEcus() Returns the library's cached list of addressable ECUs in the vehicle.
FaultCodeResponse	getCachedFaultCode(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu) Synchronously returns the last fault code received by this library for a given ECU.
Set<String>	getCachedLedNames() Returns the cached list of addressable LEDs on the WVA.
VehicleDataResponse	getCachedVehicleData(String endpoint) Synchronously returns the last value received by this library for a given endpoint.
Set<String>	getCachedVehicleDataEndpoints() Returns the library's cached list of vehicle data endpoints.
void	getConfiguration(String configPath, WvaCallback<JSONObject> callback) Fetches the current value of the given configuration item.
static WVA	getDevice(String hostname, HttpClient client, VehicleData vehicleData, Ecus ecus, Hardware hw, FaultCodes fc) WVA Object Factory.
boolean	isEventChannelDisconnected() Returns true if the WVA's EventChannel is currently stopped, or non-existent, implying that no data is coming into the system.
void	isWVA(WvaCallback<Boolean> callback) Make a reasonable guess as to whether the device with which we are communicating is in fact a WVA.
void	removeAllFaultCodeListeners() Removes all listeners associated with any ECU, as well as the "catch-all" listener, if any.
void	removeAllVehicleDataListeners() Removes all listeners associated with any endpoint name, as well as the "catch-all" listener, if any.
void	removeFaultCodeListener() Removes any FaultCodeListener that has been set to be invoked on new fault code data.
void	removeFaultCodeListener(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu) Removes any FaultCodeListener that has been set to be invoked on new fault code data matching the given bus, type and ECU.
void	removeVehicleDataListener() Removes any VehicleDataListener that has been set to be invoked on new vehicle data.
void	removeVehicleDataListener(String endpoint) Removes any VehicleDataListener that has been set to be invoked on new vehicle data pertaining to the given endpoint.
void	setEventChannelStateListener(EventChannelStateListener listener) Sets the listener to be used to receive information about the connection state of the event channel.
void	setFaultCodeListener(FaultCodeListener listener) Sets the FaultCodeListener to be invoked when any fault code data arrives via the event channel.
void	setFaultCodeListener(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, FaultCodeListener listener) Sets the FaultCodeListener to be invoked when a new fault code event, matching the given bus, type and ECU, arrives via the event channel.
WVA	setHttpPort(int port) Change the port used for HTTP requests on this WVA.
WVA	setHttpsPort(int port) Change the port used for HTTPS requests on this WVA.
void	setLedState(String ledName, boolean state, WvaCallback<Boolean> callback) Asynchronously sends a request to the WVA to set the state of the given LED.
void	setTime(DateTime time, WvaCallback<DateTime> callback) Asynchronously sends a request to the WVA to set its time to match the given value.
void	setVehicleDataListener(String endpoint, VehicleDataListener listener) Sets the VehicleDataListener to be invoked when a new vehicle data event pertaining to the given endpoint arrives via the event channel.
void	setVehicleDataListener(VehicleDataListener listener) Sets the VehicleDataListener to be invoked when any vehicle data arrives via the event channel.
void	subscribeToFaultCodes(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, int interval, WvaCallback<Void> callback) Subscribe to fault code information from the specified ECU on the WVA.
void	subscribeToVehicleData(String endpoint, int interval) Calls subscribeToVehicleData(String, int, WvaCallback) with a null callback, meaning no direct feedback as to the success or failure of the request will be available.
void	subscribeToVehicleData(String endpoint, int interval, WvaCallback<Void> callback) Subscribe to the given vehicle data endpoint on the WVA.
void	unsubscribeFromFaultCodes(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, WvaCallback<Void> callback) Unsubscribes from the specified fault code information on the WVA, by deleting the subscription record on the device.
void	unsubscribeFromVehicleData(String endpoint) Calls unsubscribeFromVehicleData(String, WvaCallback) with a null callback, meaning no direct feedback as to the success or failure of the request will be available.
void	unsubscribeFromVehicleData(String endpoint, WvaCallback<Void> callback) Unsubscribes from the given endpoint on the WVA, by deleting the subscription record on the device.
WVA	useBasicAuth(String username, String password) Sets the basic authentication credentials (username and password) to be used when interacting with the WVA over HTTP or HTTPS.
WVA	useSecureHttp(boolean secure) Sets whether HTTP communication with the WVA should be done through HTTP or HTTPS.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WVA

public WVA(String hostname)

WVA Constructor.

Note: By default, interactions with the WVA over HTTP will be done using HTTP (not HTTPS), and without any basic authentication. The methods useBasicAuth(String, String) and useSecureHttp(boolean) can be used to configure this object to use the correct settings.

Parameters:

hostname - the hostname/IP address of the WVA device

Method Detail

getDevice

public static WVA getDevice(String hostname,
            HttpClient client,
            VehicleData vehicleData,
            Ecus ecus,
            Hardware hw,
            FaultCodes fc)

WVA Object Factory. Useful for unit-testing, or if you plan on subclassing any of the sub-components of the WVA object.

Returns:

WVA

useBasicAuth

public WVA useBasicAuth(String username,
               String password)

Sets the basic authentication credentials (username and password) to be used when interacting with the WVA over HTTP or HTTPS.

Basic authentication can be removed using clearBasicAuth().

Parameters:

username - the basic auth username

password - the basic auth password

Returns:

this WVA object, for chaining purposes

clearBasicAuth

public WVA clearBasicAuth()

Clears any previously-set basic authentication for HTTP or HTTPS requests.

Basic authentication can be set using useBasicAuth(String, String).

Returns:

this WVA object, for chaining purposes

useSecureHttp

public WVA useSecureHttp(boolean secure)

Sets whether HTTP communication with the WVA should be done through HTTP or HTTPS.

Parameters:

secure - true to use HTTPS, false to use HTTP

See Also:

setHttpPort(int), setHttpsPort(int)

setHttpPort

public WVA setHttpPort(int port)

Change the port used for HTTP requests on this WVA.

Parameters:

port - the port to use

Returns:

this WVA object, for chaining purposes

See Also:

useSecureHttp(boolean)

setHttpsPort

public WVA setHttpsPort(int port)

Change the port used for HTTPS requests on this WVA.

Parameters:

port - the port to use

Returns:

this WVA object, for chaining purposes

See Also:

useSecureHttp(boolean)

setEventChannelStateListener

public void setEventChannelStateListener(EventChannelStateListener listener)

Sets the listener to be used to receive information about the connection state of the event channel.

If the event channel has been created and has not been disconnected, this method will also immediately set this listener to be used there. Otherwise, it holds onto this listener object, so that it can be passed into a future EventChannel instance, such as when calling connectEventChannel(int).

Parameters:

listener - the state listener to use with the event channel

connectEventChannel

public void connectEventChannel(int port,
                       EventChannelStateListener listener)

Turns on the TCP stream which conveys subscription and alarm data. Subscriptions and alarms can be created without the stream, but no data will be received by the library until the event channel has been connected.

This calls disconnectEventChannel() first, to ensure that we only have one EventChannel and EventDispatcher active at any one time.

If listener is null, then this method will instead use the most recent value passed into setEventChannelStateListener(EventChannelStateListener), or null if that has never been set.
When the EventChannel constructor is passed in a null listener, it generates a default listener which:

• Does nothing in onConnected, onError, or onFailedConnection
• Calls reconnectAfter with 15000 (15 seconds) in onRemoteClose, so that it automatically attempts to keep a connection open

Parameters:

port - the TCP port to connect to for the event channel

listener - a listener for the connection state

connectEventChannel

public void connectEventChannel(int port)

Convenience method for connectEventChannel(int, EventChannelStateListener), passing in null for the listener.

disconnectEventChannel

public void disconnectEventChannel(boolean disallowReconnect)

Disconnects from the event channel conveying subscription and alarm data. This does not remove the subscriptions or alarms at the device level.

Parameters:

disallowReconnect - if set to true, calls EventChannelStateListener.stopReconnects() on the currently-set state listener, so that if it calls reconnectAfter, it will not actually attempt to reconnect

disconnectEventChannel

public void disconnectEventChannel()

Disconnects from the event channel. Calls disconnectEventChannel(boolean) with false, thus allowing future reconnects to occur. If you do not wish to connect again in the future, call disconnectEventChannel(boolean) with true.

isEventChannelDisconnected

public boolean isEventChannelDisconnected()

Returns true if the WVA's EventChannel is currently stopped, or non-existent, implying that no data is coming into the system.

Returns:

true if the event channel has been stopped (or has not been created yet)

configurePort

@Deprecated
public void configurePort(int port,
                            WvaCallback<Integer> callback)

Deprecated. As of version 2.0, prefer using configure(String, JSONObject, WvaCallback)

Sets the port on the WVA device which should be used to convey the data stream. This call may make the data stream unavailable for multiple seconds as the internal state of the device is reset.

This method is now deprecated in favor of configure:

     JSONObject data = new JSONObject();
     data.put("enable", enabled ? "on" : "off");
     data.put("port", ws_port);

     wva.configure("ws_events", data, new WvaCallback<Void>() {...});
     

Parameters:

port - The port on the device which should be used.

callback - Executed when the device responds

configureBaudRate

@Deprecated
public void configureBaudRate(int baudRate,
                                WvaCallback<Integer> callback)

Deprecated. As of version 2.0, prefer using configure(String, JSONObject, WvaCallback)

Sets the baud rate for the connection between the WVA device and the CAN bus interface. This call may make the data stream unavailable for multiple seconds as the internal state of the device is reset.

This method is now deprecated in favor of configure:

     JSONObject data = new JSONObject();
     data.put("enable", "on");
     data.put("rate", 250000);

     wva.configure("canbus/1", data, new WvaCallback<Void>() {...});
     

Parameters:

baudRate - The intended baud rate for the canbus connection

callback - Executed when the device responds

configure

public void configure(String configPath,
             JSONObject configObject,
             WvaCallback<Void> callback)

Applies the given JSON object as configuration parameters on the specified configuration web services path.

This method will intelligently wrap the given JSONObject inside of another object, with the correct key extracted from configPath. This means that in order to change, for example, the settings under canbus/1, configObject should look like this:

     {
         "enable": "on",
         "rate": 250000
     }
     

as opposed to this:

     {
         "canbus": {
             "enable": "on",
             "rate": 250000
         }
     }
     

A nearly complete example of using this API is as follows:

     private void configureHttpsServer(final boolean enable, final int port) {
         JSONObject data = new JSONObject();
         try {
             data.put("enable", enable ? "on" : "off");
             data.put("port", port);
         } catch (JSONException e) {
             Log.e("example", "JSON exception", e);
             return;
         }

         myWVA.configure("https", data, new WvaCallback<Void>() {
             // ...
         });
     }
     

This method uses an HttpClient.ExpectEmptyCallback internally, which means that there will be an error passed back to the callback if the request is successful but there is some body content. This should not happen under normal circumstances with the WVA, however.

Parameters:

configPath - the ws/config/ path to configure, e.g. "ws_events" or "canbus/1"

configObject - the configuration to be applied, in JSON format

callback - Executed when the HTTP response is received, or if there is an exception before executing the HTTP request.

getConfiguration

public void getConfiguration(String configPath,
                    WvaCallback<JSONObject> callback)

Fetches the current value of the given configuration item.

This method will intelligently unwrap the configuration object from a successful response, in the same way that configure wraps its JSONObject argument before sending it down via web services. For example, if a query to "http" returns

     {
         "http": {
             "enable": "on",
             "port": 80
         }
     }
     

then callback's onResponse method will be given just

     {
         "enable": "on",
         "port": 80
     }
     

Parameters:

configPath - the ws/config/ path to query, e.g. "ws_events" or "canbus/1"

callback - callback to be executed once the request is completed

isWVA

public void isWVA(WvaCallback<Boolean> callback)

Make a reasonable guess as to whether the device with which we are communicating is in fact a WVA. This is done by querying /ws/ and comparing the list of web services listed to services we know are present on a WVA.

callback onResponse arguments will be as follows:

• null, true if the /ws/ response indicates that this is in fact a WVA device
• null, false if the /ws/ response does not seem to indicate that this is a WVA device
• <error>, false if an exception is encountered while parsing the response as JSON, or

Parameters:

callback - a callback to be executed once we have queried /ws/ and have decided whether this is a WVA or not

fetchVehicleDataEndpoints

public void fetchVehicleDataEndpoints(WvaCallback<Set<String>> onInitialized)

Initializes the cache of vehicle data endpoint names.

The set of Strings passed into the callback will also be cached.

Parameters:

onInitialized - callback to be executed once the request has completed

See Also:

getCachedVehicleDataEndpoints()

fetchVehicleData

public void fetchVehicleData(String endpoint,
                    WvaCallback<VehicleDataResponse> callback)

Asynchronously queries the WVA for the newest data at the given endpoint. If the query is successful, the value will be cached and passed into the given callback.

Note that this is a relatively resource-intensive request and intended to be an ad-hoc operation. Instead of using this method in a loop to retrieve values, create a subscription to receive new information as it becomes available.

Parameters:

endpoint - The data endpoint to query

callback - The callback to handle the response.

See Also:

getCachedVehicleData(String)

setVehicleDataListener

public void setVehicleDataListener(VehicleDataListener listener)

Sets the VehicleDataListener to be invoked when any vehicle data arrives via the event channel.

Parameters:

listener - the listener to be invoked with all event channel vehicle data

See Also:

setVehicleDataListener(String, com.digi.wva.async.VehicleDataListener), removeVehicleDataListener()

removeVehicleDataListener

public void removeVehicleDataListener()

Removes any VehicleDataListener that has been set to be invoked on new vehicle data.

See Also:

setVehicleDataListener(com.digi.wva.async.VehicleDataListener)

setVehicleDataListener

public void setVehicleDataListener(String endpoint,
                          VehicleDataListener listener)

Sets the VehicleDataListener to be invoked when a new vehicle data event pertaining to the given endpoint arrives via the event channel. These events can be subscription or alarm updates.

If you have configured both a listener for a given endpoint ("EngineSpeed", for instance), and the catch-all listener (using setVehicleDataListener(com.digi.wva.async.VehicleDataListener)), then the listener set using this method will be invoked first on new events.

Parameters:

endpoint - the endpoint with which to associate this listener

listener - the listener to be invoked with matching event channel vehicle data

Throws:

NullPointerException - if listener is null. (Use removeVehicleDataListener(String) for that purpose)

See Also:

removeVehicleDataListener(String)

removeVehicleDataListener

public void removeVehicleDataListener(String endpoint)

Removes any VehicleDataListener that has been set to be invoked on new vehicle data pertaining to the given endpoint.

Parameters:

endpoint - the endpoint whose listener is to be removed

See Also:

setVehicleDataListener(String, com.digi.wva.async.VehicleDataListener)

removeAllVehicleDataListeners

public void removeAllVehicleDataListeners()

Removes all listeners associated with any endpoint name, as well as the "catch-all" listener, if any.

This only removes listeners from the library's internal maps. It does not delete any subscriptions or alarms from the WVA device itself.

subscribeToVehicleData

public void subscribeToVehicleData(String endpoint,
                          int interval)

Calls subscribeToVehicleData(String, int, WvaCallback) with a null callback, meaning no direct feedback as to the success or failure of the request will be available.

subscribeToVehicleData

public void subscribeToVehicleData(String endpoint,
                          int interval,
                          WvaCallback<Void> callback)

Subscribe to the given vehicle data endpoint on the WVA.

When a subscription is created for an endpoint, that endpoint will automatically update at regular intervals. This is the preferred method of receiving vehicle data from the WVA device because it does not have to create an HTTP connection for every piece of data received.

Note that the WVA Android library will maintain only one subscription record for each vehicle data endpoint, meaning that if you subscribe to "EngineSpeed" once at an interval of 15 seconds, then later subscribe with an interval of 10 seconds, that original subscription record will be overwritten.

See setVehicleDataListener(String, VehicleDataListener) for information on configuring a callback to be invoked each time subscription data arrives for the given endpoint.

Parameters:

endpoint - The type of information.

interval - The interval of time between updates

callback - callback to give feedback on whether the subscription call succeeds or not

unsubscribeFromVehicleData

public void unsubscribeFromVehicleData(String endpoint,
                              WvaCallback<Void> callback)

Unsubscribes from the given endpoint on the WVA, by deleting the subscription record on the device.

This method will only delete a subscription created by the WVA Android library (or one with a name matching <endpoint>~sub).

Parameters:

endpoint - The name of the data endpoint for which to unsubscribe

callback - callback to give feedback on whether the unsubscribe call succeeds or not

unsubscribeFromVehicleData

public void unsubscribeFromVehicleData(String endpoint)

Calls unsubscribeFromVehicleData(String, WvaCallback) with a null callback, meaning no direct feedback as to the success or failure of the request will be available.

createVehicleDataAlarm

public void createVehicleDataAlarm(String endpoint,
                          AlarmType type,
                          float threshold,
                          int seconds,
                          WvaCallback<Void> callback)

Create an alarm on the given vehicle data endpoint on the WVA. Alarms are similar to subscriptions, but they do not occur at regular intervals. Instead, alarms produce data when special conditions occur; see the JavaDoc for AlarmType for more information about the capabilities of alarms.

Note that the WVA Android library will maintain only one alarm record for each alarm type on each vehicle data endpoint, meaning that if you create an alarm for "EngineSpeed" going above 50, then later create an alarm for "EngineSpeed" going above 30, the original alarm record (for above-50) will be overwritten.

See setVehicleDataListener(String, VehicleDataListener) for information on configuring a callback to be invoked each time alarm data arrives for the given endpoint.

Parameters:

endpoint - The name of the data endpoint to add an alarm to

type - The type of alarm to create. One endpoint can't have two alarms of the same type

threshold - The threshold for the alarm. The meaning of this value depends on the alarm type

seconds - The minimum number of seconds before two alarms of the same type will be generated (for instance, only send an alarm for speeding once in a five-minute period)

callback - callback to give feedback on whether the alarm creation succeeds or not

createVehicleDataAlarm

public void createVehicleDataAlarm(String endpoint,
                          AlarmType type,
                          float threshold,
                          int seconds)

Calls createVehicleDataAlarm(String, AlarmType, float, int, WvaCallback) with a null callback, meaning no direct feedback as to the success or failure of the request will be available.

deleteVehicleDataAlarm

public void deleteVehicleDataAlarm(String endpoint,
                          AlarmType type,
                          WvaCallback<Void> callback)

Removes the alarm on the given vehicle data endpoint on the WVA, by deleting the alarm record on the device.

This method will only delete an alarm created by the WVA Android library (or one with a name matching <endpoint>~<type>).

Parameters:

endpoint - The name of the data endpoint to remove an alarm from

type - The type of alarm which should be removed

callback - callback to give feedback on whether the alarm deletion succeeds or not

deleteVehicleDataAlarm

public void deleteVehicleDataAlarm(String endpoint,
                          AlarmType type)

Calls deleteVehicleDataAlarm(String, AlarmType, WvaCallback) with a null callback, meaning no direct feedback as to the success or failure of the request will be available.

getCachedVehicleData

public VehicleDataResponse getCachedVehicleData(String endpoint)

Synchronously returns the last value received by this library for a given endpoint. No networking is involved in this request.

This cached value is only updated by subscriptions, alarms, and direct querying of the data through the library.

Parameters:

endpoint - the name of the vehicle data endpoint to look up

Returns:

most recent, cached value for the given vehicle data endpoint, or null if no value is cached currently

See Also:

subscribeToVehicleData(String, int, WvaCallback), createVehicleDataAlarm(String, AlarmType, float, int, WvaCallback), fetchVehicleData(String, WvaCallback)

getCachedVehicleDataEndpoints

public Set<String> getCachedVehicleDataEndpoints()

Returns the library's cached list of vehicle data endpoints.

Returns:

the cached list of vehicle data endpoints, or an empty set if no cached values are available

See Also:

fetchVehicleDataEndpoints(WvaCallback)

fetchFaultCode

public void fetchFaultCode(FaultCodes.Bus bus,
                  FaultCodes.MessageType type,
                  String ecu,
                  WvaCallback<FaultCodeResponse> callback)

Asynchronously queries the WVA for the most recent DTC report of the given type (active or inactive) on the given CAN bus. If the query is successful, the value will be cached and passed into the given callback.

callback onResponse arguments will be as follows:

• null, <response> if a fault code is successfully retrieved
• <exception>, null if an exception is encountered while performing the query or processing its response
• null, null if the WVA responded with an HTTP 503 error, indicating that the referenced ECU is expected to be valid, but no PGN 65227 message has yet been received
• NotListeningToECUException, null if the WVA responded with an HTTP 404 error, generally indicating that the system is not listening for trouble codes on the referenced ECU.

Note that this is a relatively resource-intensive request and intended to be an ad-hoc operation. Instead of using fetchFaultCode() in a loop to check for problems, create a subscription to receive new information as it arrives.

Parameters:

bus - which CAN bus to look at

type - the message type to query for (active or inactive)

ecu - the ECU name/identifier whose most recent fault code (if any) is being queried

callback - the callback to give feedback on whether the request succeeded, and the retrieved value if any

subscribeToFaultCodes

public void subscribeToFaultCodes(FaultCodes.Bus bus,
                         FaultCodes.MessageType type,
                         String ecu,
                         int interval,
                         WvaCallback<Void> callback)
                           throws JSONException

Subscribe to fault code information from the specified ECU on the WVA.

When a subscription is created for fault codes, that value will automatically update at regular intervals. This is the preferred method of periodically receiving fault code data from the WVA device because it does not have to create an HTTP connection for every piece of data received.

Note that the WVA Android library will maintain only one subscription record for any given bus/type/ecu combination, meaning that if you subscribe to (CAN0, ACTIVE, "ecu0") with an interval of 15 seconds, and then later subscribe with an interval of 10 seconds, that original subscription record will be overwritten.

See setFaultCodeListener(FaultCodes.Bus, FaultCodes.MessageType, String,FaultCodeListener) for information on configuring a callback to be invoked each time that matching fault code data arrives via the event channel.

Parameters:

bus - which CAN bus to look at

type - the message type to query for (active or inactive)

ecu - the ECU name/identifier whose most recent fault code (if any) is being queried

interval - the subscription interval, in seconds

callback - the callback to be executed when this HTTP request completes

Throws:

JSONException - If an error occurs while creating the request

setFaultCodeListener

public void setFaultCodeListener(FaultCodeListener listener)

Sets the FaultCodeListener to be invoked when any fault code data arrives via the event channel.

Parameters:

listener - the listener to be invoked with all event channel fault code data

See Also:

setFaultCodeListener(com.digi.wva.device.FaultCodes.Bus, com.digi.wva.device.FaultCodes.MessageType, String, com.digi.wva.async.FaultCodeListener), removeFaultCodeListener()

removeFaultCodeListener

public void removeFaultCodeListener()

Removes any FaultCodeListener that has been set to be invoked on new fault code data.

See Also:

setFaultCodeListener(com.digi.wva.async.FaultCodeListener)

setFaultCodeListener

public void setFaultCodeListener(FaultCodes.Bus bus,
                        FaultCodes.MessageType type,
                        String ecu,
                        FaultCodeListener listener)

Sets the FaultCodeListener to be invoked when a new fault code event, matching the given bus, type and ECU, arrives via the event channel.

If you have configured both a listener for a given ECU, and the catch-all listener (using setFaultCodeListener(FaultCodeListener)), then the listener set using this method will be invoked first.

Parameters:

bus - which CAN bus to look at

type - the message type

ecu - the ECU name

listener - the listener to be invoked with matching event channel fault code data

Throws:

NullPointerException - if listener is null. (Use removeFaultCodeListener(com.digi.wva.device.FaultCodes.Bus, com.digi.wva.device.FaultCodes.MessageType, String) for that purpose)

See Also:

removeFaultCodeListener(com.digi.wva.device.FaultCodes.Bus, com.digi.wva.device.FaultCodes.MessageType, String)

removeFaultCodeListener

public void removeFaultCodeListener(FaultCodes.Bus bus,
                           FaultCodes.MessageType type,
                           String ecu)

Removes any FaultCodeListener that has been set to be invoked on new fault code data matching the given bus, type and ECU.

Parameters:

bus - the CAN bus

type - the message type

ecu - the ECU name

See Also:

setFaultCodeListener(com.digi.wva.device.FaultCodes.Bus, com.digi.wva.device.FaultCodes.MessageType, String, com.digi.wva.async.FaultCodeListener)

removeAllFaultCodeListeners

public void removeAllFaultCodeListeners()

Removes all listeners associated with any ECU, as well as the "catch-all" listener, if any.

This only removes listeners from the library's internal maps. It does not delete any subscriptions or alarms from the WVA device itself.

unsubscribeFromFaultCodes

public void unsubscribeFromFaultCodes(FaultCodes.Bus bus,
                             FaultCodes.MessageType type,
                             String ecu,
                             WvaCallback<Void> callback)

Unsubscribes from the specified fault code information on the WVA, by deleting the subscription record on the device.

This method will only delete a subscription created by the WVA Android library (or one with a name matching <bus>_<type>~<ecu>~dtcsub).

Parameters:

bus - the CAN bus

type - the message type

ecu - the ECU name

callback - callback to give feedback on whether the unsubscribe call succeeds or not

createFaultCodeAlarm

public void createFaultCodeAlarm(FaultCodes.Bus bus,
                        FaultCodes.MessageType type,
                        String ecu,
                        int seconds,
                        WvaCallback<Void> callback)
                          throws JSONException

Create an alarm for fault code data from the given ECU on the WVA. Alarms are similar to subscriptions, but they do not occur at regular intervals. Instead, alarms produce data when special conditions occur; see the JavaDoc for AlarmType for more information about the capabilities of alarms.

"Change" (AlarmType.CHANGE) is the only reasonable alarm type for fault code data. As such, this method does not take in any alarm type or threshold parameters; instead, it defaults to the "Change" alarm type.

Note that the WVA Android library will maintain only one alarm record for each fault code ECU (as specified by CAN bus identifier, message type, and ECU name), meaning that if you create an alarm on (CAN0, ACTIVE, "ecu0") with an interval of 30 seconds, then later create another such alarm with an interval of 60 seconds, that original alarm record will be overwritten.

See setFaultCodeListener(com.digi.wva.device.FaultCodes.Bus, com.digi.wva.device.FaultCodes.MessageType, String, com.digi.wva.async.FaultCodeListener) for information on configuring a callback to be invoked each time alarm data arrives for the given ECU.

Parameters:

bus - which CAN bus to look at

type - the message type to query for (active or inactive)

ecu - the ECU name/identifier whose most recent fault code (if any) is being queried

seconds - the minimum number of seconds before two alarms will be generated for this ECU (for instance, only send an alarm for ecu0 fault codes once every 300 seconds)

callback - callback to give feedback on whether the alarm creation succeeds or not

Throws:

JSONException - if an error occurs in generating the JSON data being sent to the WVA to create the alarm

deleteFaultCodeAlarm

public void deleteFaultCodeAlarm(FaultCodes.Bus bus,
                        FaultCodes.MessageType type,
                        String ecu,
                        WvaCallback<Void> callback)

Removes the alarm on the given fault code data on the WVA, by deleting the alarm record on the device.

This method will only delete an alarm created by the WVA Android library (or one with a name matching <bus>_<type>~<ecu>~change).

Parameters:

bus - the CAN bus

type - the message type

ecu - the ECU name

callback - callback to give feedback on whether the alarm deletion succeeds or not

getCachedFaultCode

public FaultCodeResponse getCachedFaultCode(FaultCodes.Bus bus,
                                   FaultCodes.MessageType type,
                                   String ecu)

Synchronously returns the last fault code received by this library for a given ECU. No networking is involved in this request.

This cached value is only updated by subscriptions, alarms, and direct querying of the data through the library.

Parameters:

bus - which CAN bus the desired fault code was provided on

type - the message type to look for (active or inactive)

ecu - the name of the ECU

Returns:

most recent, cached value for the given ECU (specified by bus, type, and ECU), or null if no fault code information has been cached for this ECU

See Also:

subscribeToFaultCodes(FaultCodes.Bus, FaultCodes.MessageType, String, int, WvaCallback), createVehicleDataAlarm(String, AlarmType, float, int, WvaCallback), fetchFaultCode(FaultCodes.Bus, FaultCodes.MessageType, String, WvaCallback)

fetchFaultCodeEcuNames

public void fetchFaultCodeEcuNames(FaultCodes.Bus bus,
                          WvaCallback<Set<String>> callback)

Asynchronously queries the WVA for the list of ECUs that the system knows exist on the given CAN bus, since they might be providing active or inactive DTC messages.

This will perform an HTTP GET request on, for example, vehicle/dtc/can0_active if called with CAN0. This method does not need to be parameterized on message type, because the _active and _inactive web service URIs will return the same list of ECUs.

Parameters:

bus - the CAN bus whose ECU list is to be fetched

callback - the callback to be executed when the list of ECUs is fetched. The strings will be truncated to just the ECU name. For example, if the web service response contains the value "vehicle/dtc/can0_active/ecu0" the set will contain "ecu0"

Throws:

NullPointerException - if callback is null

setTime

public void setTime(DateTime time,
           WvaCallback<DateTime> callback)

Asynchronously sends a request to the WVA to set its time to match the given value.

The WVA Android library will automatically convert the DateTime object passed in here to UTC time, so that it is compatible with the WVA's web services.

Parameters:

time - The time to send to the WVA device (for example, DateTime.now())

callback - callback to be executed once the request has completed. The value passed in is the value that was sent to the WVA (time converted to UTC)

fetchTime

public void fetchTime(WvaCallback<DateTime> callback)

Asynchronously queries the WVA for its current time. This is a network call, so the time received by the callback could be stale by a few seconds.

Parameters:

callback - callback to be executed once the request has completed

Throws:

NullPointerException - if callback is null

fetchLedNames

public void fetchLedNames(WvaCallback<Set<String>> onInitialized)

Asynchronously queries the WVA for the list of addressable LEDs manageable by web services. The callback provided will be passed the full set of LED names in the library's cache, after successfully parsing the web services response and updating the cache.

If your code loses the string set passed into the callback, simply call getCachedLedNames() to retrieve the cached list.

Parameters:

onInitialized - callback to be executed once the request has completed

getCachedLedNames

public Set<String> getCachedLedNames()

Returns the cached list of addressable LEDs on the WVA. This will be empty unless you have called fetchLedNames(WvaCallback) first.

Returns:

the cached list of button names

fetchButtonNames

public void fetchButtonNames(WvaCallback<Set<String>> onInitialized)

Asynchronously queries the WVA for the list of addressable buttons manageable by web services. The callback provided will be passed the full set of button names in the library's cache, after successfully parsing the web services response and updating the cache.

If your code loses the string set passed into the callback, simply call getCachedButtonNames() to retrieve the cached list.

Parameters:

onInitialized - callback to be executed once the request has completed

getCachedButtonNames

public Set<String> getCachedButtonNames()

Returns the cached list of addressable buttons on the WVA. This will be empty unless you have called fetchButtonNames(WvaCallback) first.

Returns:

the cached list of button names

setLedState

public void setLedState(String ledName,
               boolean state,
               WvaCallback<Boolean> callback)

Asynchronously sends a request to the WVA to set the state of the given LED.

Parameters:

ledName - The name of the LED to modify

state - Whether or not the LED should be turned on (true means 'on')

callback - callback to be executed once the request has completed

See Also:

fetchButtonNames(WvaCallback), fetchLedState(String, WvaCallback)

fetchLedState

public void fetchLedState(String ledName,
                 WvaCallback<Boolean> callback)

Asynchronously queries the WVA for the state of the given LED.

true means the LED is on, false means it is off.

Parameters:

ledName - The name of the LED to query

callback - Executed once the LED has been queried. True means the LED is on.

Throws:

NullPointerException - if callback is null

See Also:

fetchButtonNames(WvaCallback)

fetchButtonState

public void fetchButtonState(String buttonName,
                    WvaCallback<Boolean> callback)

Asynchronously queries the WVA for the state of the given button.

true means the button is depressed.

The sensor on the device has a margin of error, and this method is intended to be used in long-press situations such as "Hold the ___ button for five seconds". Furthermore, the hardware does not currently support subscriptions, so the button must be polled; it is not recommended to use this method in a fast loop except when the button state is actually needed.

Parameters:

buttonName - The name of the button to query

callback - Executed once the button has been queried

Throws:

NullPointerException - if callback is null

fetchEcus

public void fetchEcus(WvaCallback<Set<String>> onInitialized)

Asynchronously queries the WVA for the list of addressable ECUs in the vehicle. The callback provided will be passed the full set of ECU names in the library's cache, after successfully parsing the web services response and updating the cache.

Engine control units (ECUs) are expected to be consistent throughout an entire trip, if not for the entire lifetime of the vehicle. As such, this method should only need to be called once per trip.

Each ECU in the system is referenced by a CAN bus number, and the ECU address number. A standard ECU in vehicles, for instance, is at address 0, which is defined as the primary engine. The reference designation for the engine on CAN bus 1 would be "can1ecu0". Both the CAN bus number and the ECU address number in the reference designator are expressed in decimal. ECU address numbers are generally sparse.

If your code loses the string set passed into the callback, simply call getCachedEcus() to retrieve the cached list.

Parameters:

onInitialized - callback to be executed once the request has completed

getCachedEcus

public Set<String> getCachedEcus()

Returns the library's cached list of addressable ECUs in the vehicle. This will be empty unless you have called fetchEcus(WvaCallback) first.

Returns:

the cached list of addressable ECUs

fetchEcuElements

public void fetchEcuElements(String ecuName,
                    WvaCallback<Set<String>> callback)

Asynchronously queries the WVA for the list of data elements describing a specific engine control unit (ECU) in the vehicle. The callback provided will be passed the set of ECU descriptors in the library's cache, after successfully parsing the web services response and updating the cache.

Engine control units (ECUs) are expected to be consistent throughout an entire trip, if not for the entire lifetime of the vehicle. As such, this method should only need to be called once per trip.

If your code loses the string set passed into the callback, simply call getCachedEcuElements(String) to retrieve the cached list.

Parameters:

ecuName - the name of the ECU whose elements are to be queried

callback - callback to be executed once the request is completed

getCachedEcuElements

public Set<String> getCachedEcuElements(String ecuName)

Returns the library's cached list of specific ECU elements on a given ECU. This will be empty unless you have called fetchEcuElements(String, WvaCallback) first.

Parameters:

ecuName - the name of the ECU whose elements are to be looked up

Returns:

the cached list of specific ECU elements

fetchEcuElementValue

public void fetchEcuElementValue(String ecuName,
                        String element,
                        WvaCallback<String> callback)

Asynchronously queries the WVA for the value of a specific element describing a specific ECU.

Engine control units (ECUs) are expected to be consistent throughout an entire trip, if not for the entire lifetime of the vehicle. As such, this method should only need to be called once per trip.

If your code loses the string set passed into the callback, simply call getCachedEcuElementValue(String, String) to retrieve the cached list.

Parameters:

ecuName - the name of the ECU whose info is being queried

element - the name of the description element being queried, e.g. "VIN"

callback - callback to be executed once the request is completed

getCachedEcuElementValue

public String getCachedEcuElementValue(String ecuName,
                              String endpoint)

Synchronously returns the library's last cached value of a specific element of a specific ECU of the WVA. No networking is involved in this request.

This value will be null unless you have previously called fetchEcuElementValue(String, String, WvaCallback) or fetchAllEcuElementValues(String, WvaCallback).

Parameters:

ecuName - The name of the ECU

endpoint - The endpoint on that ECU to look up

Returns:

The string representation of the data for the given ECU and endpoint. Depending on the endpoint, the actual data is semantically decimal, or hexadecimal, but it is received as a String for type simplicity.

fetchAllEcuElementValues

public void fetchAllEcuElementValues(String ecuName,
                            WvaCallback<android.util.Pair<String,String>> callback)

Fetches all endpoints from a single ECU, calling the provided callback's onResponse method with the data from every endpoint.

This is a relatively resource-intensive call, but it should only have to be performed once per ECU; the data is completely static and can just be accessed from the local cache.

Parameters:

ecuName - the ECU to query

callback - an action to be performed when each individual response is received. The first value of the pair will always be the name of the element which was queried; the second value will be null if there was an error, or the string value if the query succeeded

Throws:

IllegalStateException - if getCachedEcuElements(String) returns null or an empty set (meaning that there are no cached ECU element names for this ECU)