com.gtosoft.libvoyager.android
Class ELMBT

java.lang.Object
  extended by com.gtosoft.libvoyager.android.ELMBT

public class ELMBT
extends java.lang.Object

This class connects to, and remains connected to, the given bluetooth device. This class DOES NOT send any data to the device on its own accord. Instead, data must be sent by a parent class. - This ensures that the calling class can be in any state such as ATMA monitor-all, and we won't disrupt that. Exception 1: Upon connecting, we may go out and query the connected device with a few AT commands for statistical purposes.


Constructor Summary
ELMBT(BluetoothAdapter defaultAdapter, java.lang.String peerMACAddress)
          Constructor...
 
Method Summary
 void cancelCurrentSleeps()
          May be called by outsiders to tell us to bust out of any sleeps we might be in.
 void cancelSniff()
          We cancel a sniff (ATMA/ATMT/ATMR) session by sending a single space character.
 boolean checkBluetoothSettings()
          - Check the system bluetooth settings and make sure bluetooth is enabled and ready for use! - This method may kick off a dialog to the user to request that bluetooth be enabled.
 java.lang.String clearInputBuffer()
          Clears the input buffer such as before we send an AT command...
 java.lang.String getAdapterMAC()
          Rerturns the MAC address of the device's bluetooth device.
 long getATLoopCount(java.lang.String atCommand, int testDuration)
          See how many AT commands we can send in the given time interval.
 long getBytesIn()
          Passes the value of the input byte counter.
 java.lang.String getCANErrorCounts()
          Convenience method to get the response from the ELM ATCS command.
 int getNumFailedConnects()
           
 int getNumInputBytesBuffered()
          Shall return the number of bytes currently queued within the inputStream buffer.
 int getNumMaxRetries()
           
 java.lang.String getPeerMAC()
           
 java.lang.String getPeerName()
           
 int getProtocolNumber()
          Returns the ELM327 ATDPN protocol number.
 java.lang.String getProtocolString()
          Performs a query against the ELM device and returns the protocol description (ATDP)
 long getReadRate()
          Returns the read rate in bytes per second.
 GeneralStats getStats()
           
 long getTimeInCurrentState()
           
 long getTimeSinceLastConnect()
           
 int inputBytesAvailable()
          Wrapper method for getting number of bytes in the input buffer.
 boolean isCANErrorFree()
          Check the CAN error counters.
 boolean isConnected()
          Note: After a successful connect() we won't know a disconnect happened until the I/O failcount goes up high enough to suggest that the connection is dead.
 boolean isIODoneTrying()
           
 boolean isValidATResponse(java.lang.String request, java.lang.String response)
           
 void notifyBluetoothDisconnected(java.lang.String address)
          Call this method with the MAC of a bluetooth device which we just disconnected from.
 java.lang.String readInputBuffer_string(char UpToThisCharacter)
          Reads all bytes from the input buffer UP TO 4K.
 java.lang.String readInputBuffer(char UpToThisCharacter)
           
 java.lang.String readUpToCharacter(char stopAtThisCharacter, int maxWaitSeconds)
          Loop if necessary (limited by a timeout value) to read data from input buffer up to and including the prompt character.
 java.lang.String readUpToPrompt()
          Convenience method to read up to the prompt character.
 void reconnectIfDisconnected(boolean truetoReconnect)
          This method lets you specify whether or not the bluetooth connection should be re-established in the event that it dies.
 void registerMessageCallback(EventCallback eventCallback)
          A means for a parent class to receive messages generated by this class.
 void registerStateChangeCallback(EventCallback eventCallback)
          A away for calling class to register a method to get fired off when our state changes (when we disconnect or connect).
 java.lang.String sendATCommand(java.lang.String ATCommand)
          Send a single AT command and return the response.
 java.lang.String sendATCommand2(java.lang.String cmd)
          Send AT command, return only the response data.
 java.lang.String sendATCommandWithRetry(java.lang.String ATCommand)
          Like sendATCommand except: 1.
 boolean sendATInitialization(java.lang.String[] atCommands)
          Send a series of AT commands, one after another, only proceeding if the last succeeded.
 java.lang.String sendOBDCommand(java.lang.String Command)
          Send a command to the device, it can be an OBD command...
 boolean sendRaw(java.lang.String sendThis)
          // * Send the exact string provided.
 void setConnectRetryPeriod(int retryPeriodInSeconds)
          sets the number of seconds to wait in between connect re-tries.
 void setIOReconnectNOW()
          Will kick the I/O Layer into trying to connect again.
 void setIOStopTryingToConnect()
           
 void setMaxRetries(int maxRetries)
           
 void shutdown()
          Shut down this class.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ELMBT

public ELMBT(BluetoothAdapter defaultAdapter,
             java.lang.String peerMACAddress)
Constructor...

Parameters:
numHeaderBits - - 11 or 29
defaultAdapter - - just pass us an adapter. You can do it since you have the context. We're just a java class without the context to grab the default adapter.
peerMACAddress - - MAC address, all uppercase, of the Bluetooth peer for which we are to connect.
Method Detail

getTimeInCurrentState

public long getTimeInCurrentState()
Returns:
- returns the number of seconds we've spent in the current state.

registerMessageCallback

public void registerMessageCallback(EventCallback eventCallback)
A means for a parent class to receive messages generated by this class. Very useful for debugging.

Parameters:
eventCallback - - override the newMessage() method.

getTimeSinceLastConnect

public long getTimeSinceLastConnect()
Returns:
- returns number of seconds since we last tried to connect.

isConnected

public boolean isConnected()
Note: After a successful connect() we won't know a disconnect happened until the I/O failcount goes up high enough to suggest that the connection is dead. NEW: we will now offer a method notifyBluetoothDisconnected which can be executed, with bluetooth address, to notify us that *A* bluetooth device connected, and we can see if it was us and if so execute setConnected

Returns:
- Returns true if the bluetooth is connected and ready for I/O. False otherwise.

shutdown

public void shutdown()
Shut down this class. After a shutdown it is expected that this class instance is no longer in use.


checkBluetoothSettings

public boolean checkBluetoothSettings()
- Check the system bluetooth settings and make sure bluetooth is enabled and ready for use! - This method may kick off a dialog to the user to request that bluetooth be enabled.

Returns:
- true if its available right now, false otherwise.

registerStateChangeCallback

public void registerStateChangeCallback(EventCallback eventCallback)
A away for calling class to register a method to get fired off when our state changes (when we disconnect or connect).

Parameters:
eventCallback - - override onStateChange().

getCANErrorCounts

public java.lang.String getCANErrorCounts()
Convenience method to get the response from the ELM ATCS command. It returns T:XX R:XX

Returns:
CAN Error counts: GOOD: "T:00 R:00" BAD(either number nonzero): "T:00 R:87"

clearInputBuffer

public java.lang.String clearInputBuffer()
Clears the input buffer such as before we send an AT command...


sendOBDCommand

public java.lang.String sendOBDCommand(java.lang.String Command)
Send a command to the device, it can be an OBD command... Response is expected to be terminated with a prompt ('>') character.

Parameters:
Command - - for example "01 00"
Returns:
- returns the string obtained from the device in response to the command.

sendATCommand

public java.lang.String sendATCommand(java.lang.String ATCommand)
Send a single AT command and return the response.

Parameters:
ATCommand - - the AT command without \r.
Returns:
- returns the string response from the device.

sendATCommand2

public java.lang.String sendATCommand2(java.lang.String cmd)
Send AT command, return only the response data. This method wraps the "sendAtCommandWithRetry()" method, so it should be fairly robust.

Parameters:
ATCommand -
Returns:

sendATCommandWithRetry

public java.lang.String sendATCommandWithRetry(java.lang.String ATCommand)
Like sendATCommand except: 1. We must see OK or ELM in the response 2. we must see the original command echo'd back. 3. We will try a few times to get a valid response. 4. if no valid response was received, we return a blank string. 5. return value is true/false, indicating success or failure.

Parameters:
ATCommand - - the AT command to send, which should result in an OK or ELM response.
Returns:
- the response string on success, otherwise a blank string.

isValidATResponse

public boolean isValidATResponse(java.lang.String request,
                                 java.lang.String response)

sendATInitialization

public boolean sendATInitialization(java.lang.String[] atCommands)
Send a series of AT commands, one after another, only proceeding if the last succeeded.

Parameters:
atCommands - - a String array containing the list of initialization commands.
Returns:
- return value is TRUE if all commands succeeded. False otherwise.

sendRaw

public boolean sendRaw(java.lang.String sendThis)
// * Send the exact string provided. We don't append a CRLF or anything like that - we just send the exact string to the device as-is.

Parameters:
sendThis - - exact string to send to the device.
Returns:
- returns true unless a problem occurs, in which case we return false;

inputBytesAvailable

public int inputBytesAvailable()
Wrapper method for getting number of bytes in the input buffer. We log errors if they occur.

Returns:
- the number of bytes waiting in the input buffer.

readUpToPrompt

public java.lang.String readUpToPrompt()
Convenience method to read up to the prompt character. Waits for new data up to about 3 seconds if necessary.

Returns:

getNumInputBytesBuffered

public int getNumInputBytesBuffered()
Shall return the number of bytes currently queued within the inputStream buffer.

Returns:

readUpToCharacter

public java.lang.String readUpToCharacter(char stopAtThisCharacter,
                                          int maxWaitSeconds)
Loop if necessary (limited by a timeout value) to read data from input buffer up to and including the prompt character. This method is used by the sniffer logic, while in sniff mode.

Returns:

readInputBuffer

public java.lang.String readInputBuffer(char UpToThisCharacter)

readInputBuffer_string

public java.lang.String readInputBuffer_string(char UpToThisCharacter)
Reads all bytes from the input buffer UP TO 4K. In the case of a device that is in sniff mode, it would read forever unless we put the byte limit (4k) on it.

Parameters:
UpToThisCharacter -
Returns:

reconnectIfDisconnected

public void reconnectIfDisconnected(boolean truetoReconnect)
This method lets you specify whether or not the bluetooth connection should be re-established in the event that it dies.

Parameters:
truetoReconnect - - set to true if you want ELMBT to reconnect if disconnected. false means we stay disconnected if the connection dies.

getATLoopCount

public long getATLoopCount(java.lang.String atCommand,
                           int testDuration)
See how many AT commands we can send in the given time interval.

Parameters:
atCommand -
testDuration -
Returns:
- returns the number of loops we performed in the given interval.

getBytesIn

public long getBytesIn()
Passes the value of the input byte counter. Increments for every byte we read.

Returns:
- returns the number of bytes read on the rfcomm interface since we connected.

getReadRate

public long getReadRate()
Returns the read rate in bytes per second.

Returns:
- returns bytes per second.

setConnectRetryPeriod

public void setConnectRetryPeriod(int retryPeriodInSeconds)
sets the number of seconds to wait in between connect re-tries.

Parameters:
retryPeriodInSeconds - - number of seconds.

setMaxRetries

public void setMaxRetries(int maxRetries)

getNumFailedConnects

public int getNumFailedConnects()

getNumMaxRetries

public int getNumMaxRetries()
Returns:
- returns the max number of times we'll try to re-connect.

getAdapterMAC

public java.lang.String getAdapterMAC()
Rerturns the MAC address of the device's bluetooth device.

Returns:
- returns a string representation of the bluetooth device's MAC address.

getPeerName

public java.lang.String getPeerName()
Returns:
- the name of the bluetooth peer device as found through discovery.

getPeerMAC

public java.lang.String getPeerMAC()
Returns:
- the MAC of the bluetooth peer device as found through discovery.

isIODoneTrying

public boolean isIODoneTrying()
Returns:
- returns true if the IO layer is done trying to reconnect.

setIOReconnectNOW

public void setIOReconnectNOW()
Will kick the I/O Layer into trying to connect again.


setIOStopTryingToConnect

public void setIOStopTryingToConnect()

cancelSniff

public void cancelSniff()
We cancel a sniff (ATMA/ATMT/ATMR) session by sending a single space character. A Space shouldn't be disruptive if we're not in a monitor session, so it is quite ideal.


notifyBluetoothDisconnected

public void notifyBluetoothDisconnected(java.lang.String address)
Call this method with the MAC of a bluetooth device which we just disconnected from. Having this method prevents us from needing to register broadcast recievers from the ELMBT layer.

Parameters:
address - - Bluetooth address, all caps.

getStats

public GeneralStats getStats()

cancelCurrentSleeps

public void cancelCurrentSleeps()
May be called by outsiders to tell us to bust out of any sleeps we might be in.


isCANErrorFree

public boolean isCANErrorFree()
Check the CAN error counters. Only applicable if connected via CAN network.

Returns:
- returns TRUE if the connection is error free. False otherwise.

getProtocolString

public java.lang.String getProtocolString()
Performs a query against the ELM device and returns the protocol description (ATDP)

Returns:

getProtocolNumber

public int getProtocolNumber()
Returns the ELM327 ATDPN protocol number.

Returns: