PakTrakr for Android

This post will be kept up-to-date about the PakTrakr for Android application I've written.

It will represent the user manual, known bug list, future goals list and application and source code availability reference.  As information is updated, I will strikeout the old, highlight the new, and mark with version numbers (1.0, 1.1, 1.2).

Comments or bug reports can be posted as comments here or emailed to mwbrown42@gmail.com.  Please provide detailed information to allow me to have a chance to reproduce and correct the problem: Android device type, Android operating system version number, screen resolution, GPS and Bluetooth availability in the device, PakTrakr Bluetooth transmitter, and other relevant device-specific information and a detailed description of the steps necessary to recreate the problem.

I will do my best to continue fixes and new development but I can't promise anything, especially with the PakTrakr product going out of business.

User Manual:

Quick Start:

1. Install a Bluetooth transmitter into your PakTrakr's serial port
2. Turn on Bluetooth service in your phone
3. Turn on GPS service in your phone
4. Pair the Bluetooth transmitter with your phone
5. Install the PakTrakr app
6. Complete all Preferences settings, including the Bluetooth transmitter ID
7. Ensure the PakTrakr is active
8. Click on the Real Data button on the Debug tab
9. You should see the PakTrakr data reflected in the gauges and battery table
10. When you're ready to drive, click on the Start Trip button on the Maps tab
11. Wait for the map display to find your location
12. Enjoy your trip!
13. When your trip is over, click the Stop Trip button on the Maps tab

Purpose:

This Android application displays battery data from a PakTrakr system through a Bluetooth link.  Unfortunately PakTrakr went out of business on 12/31/2011, so no new parts are available.

Access to the critical information about the battery pack in your vehicle (car, truck, boat, etc) helps you operate the vehicle safely and hopefully with longer range and more confidence.

The application is set up as a series of tabs.  For best performance, the Android device should be mounted / held in Landscape position.

Map Tab:

The Map tab utilizes the GPS in your Android device and the Google Maps feature to graphically track your trip distance.  To begin your trip, make sure your GPS is enabled.  Click on the Start Trip button and begin driving.  A green line representing your trip will be drawn on the satellite map.  When your trip is complete, click on the Stop Trip button.  You trip will be logged in the Trips tab.  In the future, it will dynamically calculate your remaining range given the characteristics of your current trip and the amount of charge left in your battery pack.


Gauges Tab:

(Simulated Data)

The Gauges tab displays four pieces of information about your battery pack.  These readings are only valid when you are not pressing on the electron pedal and the battery pack is not charging or discharging.

1. % Charge.  This is a dial gauge that goes from 70 to 100, showing how much charge is left in your battery pack.  This number comes directly from the PakTrakr data stream and it's not clear to me how this is calculated.  Each type of battery has a safe discharge level, so be sure to not drop below this.  
2. Pack Temp.  This is a dial gauge that goes from 20 to 160, showing the temperature in Fahrenheit, of the battery pack.  Batteries that are too cold or too hot do not charge and discharge effectively.
3. Pack Volts.  This is a dial gauge that goes from 90 to 130, showing the voltage of the battery pack.  Watch this carefully to ensure you do not over-discharge your battery pack.
4. Current Flow.  This is a bar graph that goes from -600A to 600A, showing the charging current flow, in a green bar, and the discharging current flow, in red.  Careful electric driving reduces extreme current draw.

Batteries Tab:

(Simulated Data)

The Batteries tab is a grid representing the physical location of each battery in the pack.  There is a display for each battery showing the battery number and the instantaneous voltage of that battery.  Watch each battery's level and ensure that all batteries are within a narrow voltage range and no batteries are overcharged or  over-discharged.


Trips Tab:

The Trips tab displays a list of each trip you log using the Start Trip and Stop Trip buttons on the Map tab.  To delete a trip, tap on a trip line and select Yes in the confirmation dialog.


Errors Tab:

The Errors tab displays a list of error codes emitted by the PakTrakr.  There are several types of errors, which help you understand what is happening to each battery:

Low Water Likely, Pack Imbalance, Failing Battery, Maintenance Required, Damaged Battery, Overcharging, Excessive Discharge

Each error line in this tab contains:

Date, Physical Battery Number, Error Message

Preferences Tab:

This tab configures the application to match your PakTrakr and battery installation.  You must set these parameters correctly to match your installation or problems or crashes will occur.

• Rated Battery Voltage: Tap to enter the normal voltage of your battery type.
• Low Battery Voltage:  Tap to enter the lowest safe voltage for your battery type.

• Battery Rows: Tap to enter the battery setup in your vehicle.  This section allows you to set the number of physical rows of batteries in your vehicle.  It dynamically changes the number of entries and allows you to enter the number of batteries physically located in each row in the car, going from front to back.

• PakTrakr Remotes: Tap to enter the PakTrakr wiring in your vehicle.  This section allows you to set the number of PakTrakr Remote units you have in your vehicle, and the physical battery number wired to each sensor wire of each PakTrakr Remote.  This is required due to the possibility that your battery bus wiring may not match up to the battery numbering system you'd like to use.  A Battery mapping entry is a comma-separated list of physical battery numbers, showing how each physical battery is wired to the PakTrakr Remote sensor wires, for example "3,1,2,6,5,4".  It's very important to follow the PakTrakr wiring instructions or the data reported will not match the battery layout.  The PakTrakr sensor wires go in sequence from the "Most Negative" battery in a battery group for each PakTrakr Remote to the "Most Positive" battery in the group.  The Black wire goes to the Most Negative battery's (-) terminal.  The remaining wires go to the (+) terminals of each battery in sequence: Red, Green, Blue, Orange, White, Brown, Yellow, Violet.  Any unused sensor wires can be wrapped in tape or cut off and secured.

• PakTrakr Bluetooth Device: Tap to select the name of the previously Bluetooth-paired transmitter you have attached to the PakTrakr serial port connector.  Please see this entry for more details.

Debug Tab:

This tab contains useful things I used during debugging of the application and which should go away in the future.

• Real Data / Dump Data / Simulated Data:  This switches the data being read and where it's displayed.  The app launches in Simulated Data mode.  You need to make sure your Bluetooth transmitter is on, Bluetooth is enabled on the Android device and the transmitter name is selected in the Preferences screen.  You can then click on Real Data.  After a short period to hook up to the transmitter, the PakTrakr data should be reflected on all displays and gauges.
• Test Parser:  This reads some PakTrakr test data within the app and runs it through the parser and  reflects it on all displays and gauges.
• Insert Trip:  This adds a fake trip to the Trip database and Trip list.
• Insert Error / Delete All Errors:  This adds a fake error to the Error database and Error list, or clears all errors from the database and list.
• Data Dump Area:  This is where raw PakTrakr data is displayed instead of being parsed and  reflected on all displays and gauges.

Known Bugs:

• The app is very fragile, so you may find that many things can crash it.
• GPS turned off crash.
• Bluetooth turned off crash.
• Rotate Android device crash.
• PakTrakr data signal interference crash.
• PakTrakr protocol data mis-handling crash.
• Parameter settings mis-handling incorrect operation or crash.
• Bluetooth not linking up.  Check pairing, power and wiring.  Try rebooting Android device.
• Data may not be displayed in the Data Dump area.

Updates:

• V 1.0: Initial Release.
• V 1.1: Added ACRA crash handling library to report crashes for debugging and updates.
• V 1.1: Gauges now autosize to your device's screen resolution.  Tested on Droid, Droid Bionic and Xoom.
• V 1.1: Optimized gauge layout for portrait and landscape orientation.
• V 1.2: Added error handling to Preferences inputs
• V 1.2: Improved handling of errors in PakTrakr data stream

Future Goals:

• Auto-scale the Voltage gauge for pack voltage.  Currently hardcoded to 120V.  Top of scale will be nominal @ 125%, Low will be 25%.
• Allow user to select which gauges to show or not show
• Scale the battery table to size to available space
• Use graphical AA battery and height bar/color to indicate charge level
• Calculate Watt-Hours/Mile
• Display Watt-Hours in gauge or tab
• Add Miles/Kilometers setting
• Add validation to the battery pack Preferences inputs
• Add better error handling to PakTrakr data stream
• Add better Bluetooth connection status messages
• Continuously calculate a reliable remaining distance based on the trip distance so far, starting and current charge levels, and display in the Map tab.
• Add another table to track charging information.
• Allow gauges to resize to native display on your Android device.
• Add color coding to Batteries tab for good / overcharge / over-discharged state
• Calculate average per-charge distance
• Record and display Amp-Hours during charge and driving
• Handle first notification of an error and ignore subsequent ones until error goes away
• Remove, hide or redesign Debug tab
• Re-use graphical display to talk to another brand of Battery Monitoring System.  Jack wants me to get data from a LinkPro.
• 
  

Application Availability:

The app was completed and published in the Google Play store on May 27, 2012.  Please use the button below to access it:




I will release the application temporarily from this web site.  When I have the full process in place, I will release the application into the Android Market / Google Play store.

In order to release V1.0 of the application here, I have to:

• Fix a final bug in the PakTrakr protocol handling (always one more bug!)
• Create a cryptographic key to sign the application
• Create a cryptographic key to enable the use of the Google Maps programming interface
• Create an End User License Agreement, based on GPL V3
• Set version numbers and names in the Manifest file
• Use Eclipse to create signed and optimizied .apk file
• Provide a link to the .apk file.  Note that you will have to update your device settings to allow application installation from non-Market / Play locations.

In order to release V1.0 of the application to Android Market / Google Play store, I have to:

• Complete all of the above
• Design an icon, as defined by the Android style guide (Thanks to Ryan's skills!)
• Prepare promotional text and screenshots of the application
• Configure Market / Play options
• Publish in Market / Play
• Create link to app installation icon:

Source Code Availability:

I will release the source code to the application, under the GPL V3 license, as an Eclipse project Archive file.  Anyone can download, use and update this code as long as you stay in compliance with GPL V3.  I would ask that any fixes or great new features be donated back to me for inclusion in the code for everyone's benefit.  Donations to my PayPal account mwbrown42@gmail.com for access to the source code are gratefully accepted.