public class WVA extends Object
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.runsOnUiThreadEventChannelStateListener.runsOnUiThreadVehicleDataListener.runsOnUiThreadFaultCodeListener.runsOnUiThreadThese are some of the interactions which must be run from the main thread in Android:
notifyDataSetChanged() on an adapter, etc.)
Toast notifications
The following tasks should not be done on the UI thread:
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.)
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.)
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.
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.)
| 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.
|
public WVA(String hostname)
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.
hostname - the hostname/IP address of the WVA devicepublic static WVA getDevice(String hostname, HttpClient client, VehicleData vehicleData, Ecus ecus, Hardware hw, FaultCodes fc)
public WVA useBasicAuth(String username, String password)
Basic authentication can be removed using clearBasicAuth().
username - the basic auth usernamepassword - the basic auth passwordpublic WVA clearBasicAuth()
Basic authentication can be set using useBasicAuth(String, String).
public WVA useSecureHttp(boolean secure)
secure - true to use HTTPS, false to use HTTPsetHttpPort(int),
setHttpsPort(int)public WVA setHttpPort(int port)
port - the port to useuseSecureHttp(boolean)public WVA setHttpsPort(int port)
port - the port to useuseSecureHttp(boolean)public void setEventChannelStateListener(EventChannelStateListener listener)
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).
listener - the state listener to use with the event channelpublic void connectEventChannel(int port,
EventChannelStateListener listener)
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:
onConnected,
onError, or
onFailedConnection
reconnectAfter
with 15000 (15 seconds) in onRemoteClose,
so that it automatically attempts to keep a connection open
port - the TCP port to connect to for the event channellistener - a listener for the connection statepublic void connectEventChannel(int port)
connectEventChannel(int, EventChannelStateListener), passing
in null for the listener.public void disconnectEventChannel(boolean disallowReconnect)
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 reconnectpublic void disconnectEventChannel()
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.public boolean isEventChannelDisconnected()
EventChannel is currently stopped, or non-existent, implying
that no data is coming into the system.@Deprecated public void configurePort(int port, WvaCallback<Integer> callback)
configure(String, JSONObject, WvaCallback)
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>() {...});
port - The port on the device which should be used.callback - Executed when the device responds@Deprecated public void configureBaudRate(int baudRate, WvaCallback<Integer> callback)
configure(String, JSONObject, WvaCallback)
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>() {...});
baudRate - The intended baud rate for the canbus connectioncallback - Executed when the device respondspublic void configure(String configPath, JSONObject configObject, WvaCallback<Void> callback)
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.configPath - the ws/config/ path to configure, e.g. "ws_events" or
"canbus/1"configObject - the configuration to be applied, in JSON formatcallback - Executed when the HTTP response is received, or if there is an exception before
executing the HTTP request.public void getConfiguration(String configPath, WvaCallback<JSONObject> callback)
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
}
configPath - the ws/config/ path to query, e.g. "ws_events" or
"canbus/1"callback - callback to be executed once the request is completedpublic void isWVA(WvaCallback<Boolean> callback)
/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:
/ws/ response indicates that this is
in fact a WVA device
/ws/ response does not seem to indicate that this is a WVA devicecallback - a callback to be executed once we have queried /ws/ and have decided
whether this is a WVA or notpublic void fetchVehicleDataEndpoints(WvaCallback<Set<String>> onInitialized)
The set of Strings passed into the callback will also be cached.
onInitialized - callback to be executed once the request has completedgetCachedVehicleDataEndpoints()public void fetchVehicleData(String endpoint, WvaCallback<VehicleDataResponse> 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.
endpoint - The data endpoint to querycallback - The callback to handle the response.getCachedVehicleData(String)public void setVehicleDataListener(VehicleDataListener listener)
VehicleDataListener to be invoked when
any vehicle data arrives via the event channel.listener - the listener to be invoked with all event channel vehicle datasetVehicleDataListener(String, com.digi.wva.async.VehicleDataListener),
removeVehicleDataListener()public void removeVehicleDataListener()
VehicleDataListener that has been set to be
invoked on new vehicle data.public void setVehicleDataListener(String endpoint, VehicleDataListener listener)
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.
endpoint - the endpoint with which to associate this listenerlistener - the listener to be invoked with matching event channel vehicle dataNullPointerException - if listener is null.
(Use removeVehicleDataListener(String) for that purpose)removeVehicleDataListener(String)public void removeVehicleDataListener(String endpoint)
VehicleDataListener that has been set to be
invoked on new vehicle data pertaining to the given endpoint.endpoint - the endpoint whose listener is to be removedsetVehicleDataListener(String, com.digi.wva.async.VehicleDataListener)public void removeAllVehicleDataListeners()
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.
public void subscribeToVehicleData(String endpoint, int interval)
subscribeToVehicleData(String, int, WvaCallback) with a null callback,
meaning no direct feedback as to the success or failure of the request will be available.public void subscribeToVehicleData(String endpoint, int interval, WvaCallback<Void> callback)
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.
endpoint - The type of information.interval - The interval of time between updatescallback - callback to give feedback on whether the subscription call succeeds or notpublic void unsubscribeFromVehicleData(String endpoint, WvaCallback<Void> callback)
This method will only delete a subscription created by the WVA Android library (or one with a name matching <endpoint>~sub).
endpoint - The name of the data endpoint for which to unsubscribecallback - callback to give feedback on whether the unsubscribe call succeeds or notpublic void unsubscribeFromVehicleData(String endpoint)
unsubscribeFromVehicleData(String, WvaCallback) with a null callback,
meaning no direct feedback as to the success or failure of the request will be available.public void createVehicleDataAlarm(String endpoint, AlarmType type, float threshold, int seconds, WvaCallback<Void> callback)
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.
endpoint - The name of the data endpoint to add an alarm totype - The type of alarm to create. One endpoint can't have two
alarms of the same typethreshold - The threshold for the alarm. The meaning of this value depends on the alarm typeseconds - 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 notpublic void createVehicleDataAlarm(String endpoint, AlarmType type, float threshold, int seconds)
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.public void deleteVehicleDataAlarm(String endpoint, AlarmType type, WvaCallback<Void> callback)
This method will only delete an alarm created by the WVA Android library (or one with a name matching <endpoint>~<type>).
endpoint - The name of the data endpoint to remove an alarm fromtype - The type of alarm which should be removedcallback - callback to give feedback on whether the alarm deletion succeeds or notpublic void deleteVehicleDataAlarm(String endpoint, AlarmType type)
deleteVehicleDataAlarm(String, AlarmType, WvaCallback) with a null callback,
meaning no direct feedback as to the success or failure of the request will be available.public VehicleDataResponse getCachedVehicleData(String endpoint)
This cached value is only updated by subscriptions, alarms, and direct querying of the data through the library.
endpoint - the name of the vehicle data endpoint to look upsubscribeToVehicleData(String, int, WvaCallback),
createVehicleDataAlarm(String, AlarmType, float, int, WvaCallback),
fetchVehicleData(String, WvaCallback)public Set<String> getCachedVehicleDataEndpoints()
fetchVehicleDataEndpoints(WvaCallback)public void fetchFaultCode(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, WvaCallback<FaultCodeResponse> callback)
callback onResponse arguments
will be as follows:
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.
bus - which CAN bus to look attype - the message type to query for (active or inactive)ecu - the ECU name/identifier whose most recent fault code (if any) is being queriedcallback - the callback to give feedback on whether the request succeeded, and the
retrieved value if anypublic void subscribeToFaultCodes(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, int interval, WvaCallback<Void> callback) throws JSONException
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.
bus - which CAN bus to look attype - the message type to query for (active or inactive)ecu - the ECU name/identifier whose most recent fault code (if any) is being queriedinterval - the subscription interval, in secondscallback - the callback to be executed when this HTTP request completesJSONException - If an error occurs while creating the requestpublic void setFaultCodeListener(FaultCodeListener listener)
FaultCodeListener to be invoked when any fault code data arrives
via the event channel.listener - the listener to be invoked with all event channel fault code datasetFaultCodeListener(com.digi.wva.device.FaultCodes.Bus, com.digi.wva.device.FaultCodes.MessageType, String, com.digi.wva.async.FaultCodeListener),
removeFaultCodeListener()public void removeFaultCodeListener()
FaultCodeListener that has been set to be
invoked on new fault code data.public void setFaultCodeListener(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, FaultCodeListener listener)
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.
bus - which CAN bus to look attype - the message typeecu - the ECU namelistener - the listener to be invoked with matching event channel fault code dataNullPointerException - if listener is null.
(Use removeFaultCodeListener(com.digi.wva.device.FaultCodes.Bus, com.digi.wva.device.FaultCodes.MessageType, String)
for that purpose)removeFaultCodeListener(com.digi.wva.device.FaultCodes.Bus, com.digi.wva.device.FaultCodes.MessageType, String)public void removeFaultCodeListener(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu)
FaultCodeListener that has been set to be
invoked on new fault code data matching the given bus, type and ECU.bus - the CAN bustype - the message typeecu - the ECU namesetFaultCodeListener(com.digi.wva.device.FaultCodes.Bus, com.digi.wva.device.FaultCodes.MessageType, String, com.digi.wva.async.FaultCodeListener)public void removeAllFaultCodeListeners()
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.
public void unsubscribeFromFaultCodes(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, WvaCallback<Void> callback)
This method will only delete a subscription created by the WVA Android library
(or one with a name matching <bus>_<type>~<ecu>~dtcsub).
bus - the CAN bustype - the message typeecu - the ECU namecallback - callback to give feedback on whether the unsubscribe call succeeds or notpublic void createFaultCodeAlarm(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, int seconds, WvaCallback<Void> callback) throws JSONException
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.
bus - which CAN bus to look attype - the message type to query for (active or inactive)ecu - the ECU name/identifier whose most recent fault code (if any) is being queriedseconds - 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 notJSONException - if an error occurs in generating the JSON data
being sent to the WVA to create the alarmpublic void deleteFaultCodeAlarm(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu, WvaCallback<Void> callback)
This method will only delete an alarm created by the WVA Android library
(or one with a name matching
<bus>_<type>~<ecu>~change).
bus - the CAN bustype - the message typeecu - the ECU namecallback - callback to give feedback on whether the alarm deletion succeeds or notpublic FaultCodeResponse getCachedFaultCode(FaultCodes.Bus bus, FaultCodes.MessageType type, String ecu)
This cached value is only updated by subscriptions, alarms, and direct querying of the data through the library.
bus - which CAN bus the desired fault code was provided ontype - the message type to look for (active or inactive)ecu - the name of the ECUsubscribeToFaultCodes(FaultCodes.Bus, FaultCodes.MessageType, String, int, WvaCallback),
createVehicleDataAlarm(String, AlarmType, float, int, WvaCallback),
fetchFaultCode(FaultCodes.Bus, FaultCodes.MessageType, String, WvaCallback)public void fetchFaultCodeEcuNames(FaultCodes.Bus bus, WvaCallback<Set<String>> callback)
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.
bus - the CAN bus whose ECU list is to be fetchedcallback - 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"NullPointerException - if callback is nullpublic void setTime(DateTime time, WvaCallback<DateTime> callback)
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.
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)public void fetchTime(WvaCallback<DateTime> callback)
callback - callback to be executed once the request has completedNullPointerException - if callback is nullpublic void fetchLedNames(WvaCallback<Set<String>> onInitialized)
If your code loses the string set passed into the callback, simply call
getCachedLedNames() to retrieve the cached list.
onInitialized - callback to be executed once the request has completedpublic Set<String> getCachedLedNames()
fetchLedNames(WvaCallback) first.public void fetchButtonNames(WvaCallback<Set<String>> onInitialized)
If your code loses the string set passed into the callback, simply call
getCachedButtonNames() to retrieve the cached list.
onInitialized - callback to be executed once the request has completedpublic Set<String> getCachedButtonNames()
fetchButtonNames(WvaCallback) first.public void setLedState(String ledName, boolean state, WvaCallback<Boolean> callback)
ledName - The name of the LED to modifystate - Whether or not the LED should be turned on (true means 'on')callback - callback to be executed once the request has completedfetchButtonNames(WvaCallback),
fetchLedState(String, WvaCallback)public void fetchLedState(String ledName, WvaCallback<Boolean> callback)
true means the LED is on, false means it is off.
ledName - The name of the LED to querycallback - Executed once the LED has been queried. True means the LED is on.NullPointerException - if callback is nullfetchButtonNames(WvaCallback)public void fetchButtonState(String buttonName, WvaCallback<Boolean> callback)
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.buttonName - The name of the button to querycallback - Executed once the button has been queriedNullPointerException - if callback is nullpublic void fetchEcus(WvaCallback<Set<String>> onInitialized)
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.
onInitialized - callback to be executed once the request has completedpublic Set<String> getCachedEcus()
fetchEcus(WvaCallback) first.public void fetchEcuElements(String ecuName, WvaCallback<Set<String>> callback)
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.
ecuName - the name of the ECU whose elements are to be queriedcallback - callback to be executed once the request is completedpublic Set<String> getCachedEcuElements(String ecuName)
fetchEcuElements(String, WvaCallback) first.ecuName - the name of the ECU whose elements are to be looked uppublic void fetchEcuElementValue(String ecuName, String element, WvaCallback<String> callback)
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.
ecuName - the name of the ECU whose info is being queriedelement - the name of the description element being queried, e.g. "VIN"callback - callback to be executed once the request is completedpublic String getCachedEcuElementValue(String ecuName, String endpoint)
This value will be null unless you have previously called
fetchEcuElementValue(String, String, WvaCallback) or
fetchAllEcuElementValues(String, WvaCallback).
ecuName - The name of the ECUendpoint - The endpoint on that ECU to look uppublic void fetchAllEcuElementValues(String ecuName, WvaCallback<android.util.Pair<String,String>> callback)
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.
ecuName - the ECU to querycallback - 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 succeededIllegalStateException - if getCachedEcuElements(String) returns null or an
empty set (meaning that there are no cached ECU element names for this ECU)