Revs CarPad Documentation

Overview

The Revs CarPad is a portable Android tablet-based application designed to present information about the Collier Collections automobiles housed in the Revs Car museum in Naples Florida. It is meant for the exclusive use of Revs volunteers while they are working in the museum. The purpose of this webpage is to document the design and maintenance of the CarPad app for future custodians.

Comments, suggestions, questions: whit.turner@outlook.com

Background

In 2014, Whit Turner became a volunteer at the Revs Institute shortly after it was re-opened to the public. An extensive training manual in hard copy was available to volunteers. It consisted of over one hundred pages in a large three-ring binder. It made sense to convert the manual into a portable e-reader format for volunteers to use while at the Institute, so a project was created to curate succinct facts about each car, convert the hardcopy manual to electronic form, and add hyperlinks from the facts pages for each car to the detailed write-ups in the converted manual. The Amazon Kindle Paperwhite was chosen for the hardware and Troy Marsh created the lists of facts. Whit converted the original manual text and pictures to Kindle format and the Institute purchased a handful of Kindle devices. Other content, such as the Volunteers Handbook and training materials were added. The device was dubbed the Revs EZ Guide.

After a couple of years of use, several problems emerged with the Kindles. It was cumbersome to navigate the contents for those volunteers who lacked familiarity with e-readers in general. While many volunteers were familiar with smartphones and tablets, the Kindle was a bit of a mystery and this inhibited uptake. Also, the Kindle was monochromatic, was not good at displaying images, and lacked gesture features (swiping) found in smart devices.  Finally, it lacked any multimedia capabilities and therefore no video or sound could be displayed.

Whit began to investigate a more capable platform in 2018 using an Android tablet. An initial prototype was created using a display format with collapsible/expandable information "bars" for each vehicle, along with a thumbnail image of each car. The display was scrollable so that a summary of the entire collection could be viewed with a couple of up/down swipe gestures. Touching the down arrow next to any car's name expanded a section for that car, showing facts about the car, along with buttons linking to additional information such as pictures and documents about the car. Also, a menu was added with additional sections for general information in several categories. This concept resonated with people who saw the prototype, so a new project was spun up. The new device was dubbed CarPad (a play on words with iPad). The intent of the initial display as a list of all the cars reflected our desire to make the app car-centric since that is the focus for Station Guides within the galleries.

Development

We wanted to have a small tablet that was easily portable, similar to the Kindle. Jack Sprague and I initially used Amazon Fire 7" tablets, but since the Fire is proprietary, the development environment is constrained. We eventually chose a cost-effective (~$100) Samsung 7" device, and Whit began the software creation, using the initial display concept as the starting point. The software is written in Java since that is the native programming language for Android. The primary coding tool used is Android Studio. Android Studio is a visual code editing tool that is freely available for download but requires a fairly steep learning curve. While it can be used for Java coding, Google is promoting the use of Kotlin, a derivative language. Whit decided to stick with Java for the project due to stability and familiarity. The code eventually grew to 17 Java modules (or "classes" in programmer-speak) and several thousand lines of code.

Architecture

Since the idea of the app was to make it car-centric, we needed a way to organize the data for the cars in a logical fashion. A database was ruled out since it would require database-specific knowledge for maintenance. Instead, Whit settled on a text-based format in JSON (JavaScript Object Notation), now widely used in network applications. It consists of "tags" and data, or name-value pairs. We store this as one large file in GitHub. Some of the values are actual content, while others (such as photo data) are stored as URL links to other resources. When the application is started on a tablet, this file is downloaded to the device. Prior to the download, the app is essentially content-free, so the JSON file acts as a master configuration file.

A snippet of this JSON file (showing one car) looks like this (please note this may be difficult to read on a small device due to test wrapping):

[

  {

    "id": "1",

    "make": "Porsche",

    "model": "907",

    "year": "1968",

    "thumburl": "https://revsinstitute.box.com/shared/static/wmus0bgrh9rldml5kjtdrxo0r16eabna.jpg",

    "descr": "Serial No. 907-024 Flat-eight air-cooled engine, mounted midship, twin overhead camshafts, fuel injected, 2196cc, 278hp at 8700 rpm",

    "country": "Germany",

    "gallery": "Porsche",

    "gallery_seq": "16",

    "station": "2",

    "fact1": "A refinement of 6-cyl. 910, this featured better aerodynamics & 8-cyl. engine.",

    "fact2": "Long windscreen was inspired by cockpit cover of Mirage fighter jet.",

    "fact3": "Coefficient of drag of only 00.27",

    "fact4": "Example of obsessive weight reduction: suspension springs have reduced number of coils.",

    "fact5": "Driver moved to right side for better car balance & visibility on clockwise road courses.",

    "fact6": "First Porsche to exceed 300 kph (186 mph).",

    "fact7": "This car won 12 Hours of Sebring in ‘68 by over ten laps over its sister car.",

    "fact8": "Car was raced by a rich young Bolivian, Jamie Ortiz-Patiño, in ‘69-‘70 before being tucked away for four decades.",

    "articlesurl": "https://revsinstitute.box.com/s/jx9wxorn1j7qmgmqyx0o57d77mp7gkem",

    "dashurl": "https://revsinstitute.box.com/shared/static/zcb93a6z6vl3bggvd4ofv71q45fd0910.json",

    "imagesurl": "https://revsinstitute.box.com/shared/static/hcw5b42qabczny85405vc0a3vct4dlck.json",

    "engineurl": "",

    "tcurl": "https://revs.oncell.com/en/porsche-gallery-1968-porsche-907k-263247.html",

    "aacurl": "",

    "spare": "https://revsinstitute.org/the-collection/1968-porsche-907/"

  },

The initial bracket "[" character at the head of the file marks the beginning and is paired with a matching "]" at the end of the file. Each section of the file is delimited by matching curly braces, "{" and "}". This is standard JSON markup convention. These special characters allow the parsing code in the app to correctly build an in-memory representation of the data during app initialization. The code in the app iterates over the JSON file until the end is reached.

This example JSON section is repeated for each car. As cars are added (or removed) from the collection, this file must be edited.  GitHub supports online editing but this must be done carefully since an errant character could prevent the file from being interpreted correctly by the app. The exact order of the car sections is unimportant, since the app sorts the cars based on metadata, such as volunteer station, year, make, etc. The default sort (upon app startup) is to list the cars by station number in ascending order. In addition, the cars are listed in order of "sight lines" within a particular gallery. The key to sorting by station is the label "station" and the key to sorting by sightline is "gallery_seq". Reverse sort by station (starting with station #11 and going backwards to #1) is also exposed in the sort menu. Other sorts are available: year and make. Currently, sorting by country is not implemented but could be added.

Note that station 11 is labeled in the app drop-down sort menu on the tablets as "SHOP" and is used as a placeholder for cars that are out for long-term restorations or loans.

In addition to the sorting options, users can scroll the display directly to any station such that the first car within that station appears at or near the top of the screen.

Note that the car "facts" are included in the JSON file. While we could have stored these in Box folders instead of the JSON file (and put in links to the fact files), we decided to retain the prototype structure to avoid added complexity in the app since the prototype was already coded to parse and display the facts from the JSON file.

Also note that some entries in the JSON file are URL links that point to external web resources, such as the car's corresponding web page on the Revs website or the OnCell resource for images, video, and 3D content displayed in the Revs visitors' app, which is available for anyone to download.

Additional content pointed to by some URL links is housed on the Revs' Box.com repository, organized into folders. The link is here. (an editor-level account is required to edit these files and folders). This is the working set of folders for all the CarPad content. A read-only copy is maintained for volunteers to peruse via a web browser at this link. See the section titled "Box.com Folder Structure" below for details.

Some of the JSON tags are empty or are named somewhat nonsensically. This is because as we evolved the content and purpose for each tag, it was more convenient to simply use what was available rather than re-create the whole JSON structure and risk breaking the app as it matured.

There is actually a second level of redirection that occurs for some links. These second-level links point to additional small JSON files stored in Box (in the respective car folders) which the app can interpret as pointers to collections of images (for example pictures of a car's dash) which it will display in a "gallery" of small thumbnails. When a user touches one of these, it will expand to full screen and can be zoomed and panned with fingertip gestures. For example, this JSON file points to several images stored in Box for LeMonstre:

{

    "photo1": "https://revsinstitute.box.com/shared/static/8chggw7l0ko4hm15h9ply0bsl1q5nsy5.jpg",

    "photo2": "https://revsinstitute.box.com/shared/static/l61omz63dd369oftr3365ffg2er6hrd8.jpg",

    "photo3": "https://revsinstitute.box.com/shared/static/tiusaoajly1veopvarxdzrxiy7y38i25.jpg",

    "photo4": "https://revsinstitute.box.com/shared/static/8wy1msee27lxbt97j7vfuh08qhq6a76n.jpg",

    "photo5": "",

    "photo6": "",

    "photo7": "",

    "photo8": "",

    "photo9": "",

    "photo10": "",

    "photo11": "",

    "photo12": ""

  }

The links to files within Box are generated by a Box command and can then be copied into the proper JSON file. These links are persistent.

The empty lines have no effect on the app; it simply ignores them. If they are later populated with additional links, the app will display them.

Box.com Folder Structure

We wanted to create a taxonomy (that is, a logical structure) for organizing the information for the cars. We settled on a folder structure in Box.com to line up with this taxonomy. At the top level, each car has its own folder. Under those top-level folders are sub-folders (and sub-sub folders in some cases) with additional information about each car. This also allows the information to be browsed in a read-only fashion from the Box web interface (from a copy of the "working" folder structure) without the need to use the CarPad app, so volunteers can look at the CarPad data from home.

Auxiliary Menu

In addition to the sort/scroll-to menu at the top right of the display, we created an auxiliary menu (at the top left of the main screen) to provide access to additional information. In general, these are simply URL links to either Box folders, individual documents stored in Box, or external web links. These open in an Android browser and the contents are displayed as they would be in any other browser. The formatting of the display is up to the source website. For example, Box will display a list of folders or its preview function for files.

• "People" - points to https://revsinstitute.box.com/s/7rewzpqscg4kmhi8yu7qmcnslvb7a9u1

• "Places" - points to https://revsinstitute.box.com/s/f2c1hgr0hci953sd6vbivulxgwiqu9n2

• "Technology" points to https://revsinstitute.box.com/s/ehm6aplnr79lai45wh1asty2g1mtla04

• "Training Materials" points to https://revsinstitute.box.com/s/qmiqh458ahkqgp7ivg2x6c1qz9mb6cje

• "Emergency Procedures" points to https://revsinstitute.box.com/s/lie2dhmpfgd4d36p5qygv4rlcvwpvfzt

• "Volunteer Handbook" points to https://revsinstitute.box.com/s/eahdfyeee12c6c4vep3svh5i71c5nlme

• "Revs Website" points to https://revsinstitute.org

• "Volgistics" points to https://www.volgistics.com/ex2/vicnet.dll?FROM=110030

• "Tappet Clatter Archives" points to https://revsinstitute.box.com/s/h5pttf8nmif3stwbu1yyvjar3hba5grq

• "Gallery Map" points to https://revsinstitute.box.com/s/5cl0ysmd7qvenzf2ujx0oryddwrwn53k

• "Cars Not on Display" points to https://revsinstitute.org/cars-not-on-display/

• "Provide Feedback" points to https://docs.google.com/forms/d/e/1FAIpQLSen3sbYW2d3ArXgmGFtvdMInKlPXGRNXcsVDFsg4EmlqqpaAA/viewform?usp=sf_link

• "About" points to file:///android_asset/About CarPad.html (note this is an internal link within the app)

Adding content to any of the Box resources is simply a matter of adding files in the appropriate folder. For example, if a new Tappet Clatter is available, the file simply needs to be dropped into the "Tappet Clatter - Past Issues by Year" folder on Box and it will appear when a user selects that menu option. Note to coding critics: these links are hardwired into the app, which is a horrible coding practice. This was done strictly for expediency to get the app out the door and changing it at this point would be a major pain.

When the user exits out of one of these browser sessions, cached data is released so that other users of the CarPad do not see any history information stored in the Android browser, for example, login credentials for Volgistics.

Project Team

While the software was being developed by Whit, we realized that the task of creating content required a team of people. Jack Sprague headed this up and we gathered several other volunteers to join in the effort. These were John Wharton, Mark Komenecky, Jeff Finder, and Roc Linkov. A lot of hard work was put into the curation and validation of the car facts which appear on CarPad. Jack continued to gather additional articles, photos, and kept refreshing content. He was the "editor in chief" of the CarPad content.

Revs purchased a total of 22 Samsung tablets and we launched the app in August 2019. We incorporated a feedback form inside the app which proved useful for catching typos and minor errors.

More recently (September 2023), John Wharton did a complete update/rewrite on all the car facts. These were incorporated into the JSON config file by Whit Turner

Installing the application

The following sections detail the installation process, which unfortunately requires many manual steps to prepare the tablets for single-app use. Also, these steps are needed to prevent pre-loaded apps and advertising from interfering with the CarPad app.

Installation of the App - for the older Samsung tablets

See the procedure further down the page for the newer Lenovo tablets.

From scratch setup on a new or factory reset tablet:

1. Power up, select language (should be set to English by default)

2. Connect to Revs wifi (check with Revs IT for the private network name and password)

3. Skip or decline all suggestions to create accounts or name device

4. Skip or uncheck all suggestions to provide feedback to Google

5. Don't turn on location

6. Check that the date and time are set

7. Go into settings and disable all Google applications except Chrome

8. Delete all icons on home screen and second screen (tap and drag to trashcan at top)

9. Open the Chrome browser - enter "bit.ly/carpad12" in the address bar

10. Download the file (this is the CarPad application file - it has an .apk extension)

11. Again in Chrome, navigate to "bit.ly/Carpadwall" (note uppercase C)

12. Download the file (this is the wallpaper for the home screen with a message to wait for CarPad to start up).

13. Go to settings > wallpaper and select the new wallpaper file

14. Go to "my files" app and open the apk file - you will be taken to settings > allow files from unknown sources > say OK

15. Select open to start the app after it installs

The following steps are optional but highly recommended. They convert the tablet to kiosk mode, which essentially locks the tablet on the CarPad app and prevents its use for other things. Kiosk mode prevents exiting the app. If the tablet is restarted via the power button or because the battery has discharged completely and then recharged, the app will re-launch automatically within approximately 1-3 minutes of tablet restart.

16. Go to settings > about device > tap on "build number" 7 times to enable developer mode

17. Open developer options and enable usb debugging

18. Also disable software updates

19. Connect the tablet USB port to a computer (via a USB data cable) with ADB installed *

20. Click OK on tablet popup to enable USB debugging

21. From a terminal window on the computer, type:
    adb shell dpm set-device-owner com.turner.whit.revstabletv2/.AdminReceiver

22. ​And:
    adb shell appops set android TOAST_WINDOW deny

23. ​Restart tablet (long press on power button) and verify that CarPad starts (this takes approximately 60 to 120 seconds after wallpaper appears). It will be in kiosk mode.

24. Test the app

*ADB is available for Windows here:

https://dl.google.com/android/repository/platform-tools-latest-windows.zip

MacOS here:

https://dl.google.com/android/repository/platform-tools-latest-darwin.zip

To remove the app ownership (must be done from the same computer as step 19 above), use:

adb shell dpm remove-active-admin com.turner.whit.revstabletv2/.AdminReceiver

This should prevent the app from entering kiosk mode on reboot and will allow the app to be uninstalled in settings on the tablet.

If this fails, the tablet will need to be factory reset - reboot on safe mode and use factory reset option in settings.

Escaping kiosk mode on the Samsung tablet

To break out of kiosk mode, touch and hold the two buttons at the bottom of the tablet (the two controls on either side of the center home button) for about 3 seconds. This will allow access to settings and other apps on the tablet.

Current and Future Work

A new tablet was phased in for replacement of the Samsungs. Samsung is no longer making a 7" tablet and the hardware is becoming obsolete. 10 new  Lenovo Tab M7 Gen 3 tablets were purchased to replace the Samsungs in early 2022. These were numbered 1-10. In late 2023, Lenovo discontinued their 7" tablet so we are currently (Nov 2023) purchasing some of the 8" Lenovo Tab M8, Gen 4.

Lenovo Setup Steps - updated January 2023

Fully charge the new tablet.

Hold the power button for ~4 seconds, should boot to "hi there" screen.

Touch start and follow these steps in the Setup Wizard:

1. Next screen - before you get started - click next 

2. Connect to wifi - get latest credentials from IT or use the Revs open wifi

3. "getting your tablet ready screen" plays for a while ~ 2 or 3 minutes

4. Copy apps and data screen appears > click "don't copy" at lower left of screen (tiny font)

5. Choose adult on next screen - lower left

6. Sign in screen appears - click on skip at lower left - confirm skip account setup on next screen

7. Turn off use location (this also turns off scanning)

8. Turn off send usage data (scroll down to see this)

9. Accept terms

10. On the older Lenovos, you'll be asked to OK Google News download - no choice but to OK - can be uninstalled later in settings

11. Protect your tablet with lock screen - click on "not now". On newer 8" Lenovo tablets this screen is "Equipment Safety Protection" - hit skip

12. Click "skip anyway" to confirm on next screen

13. Newer Lenovos - Review additional apps screen - no choice but to hit OK

14. Complete the setup wizard

pull down from the top of screen and turn off and turn off Bluetooth if it is on

On newer 8" Lenovos, access settings by pulling down from the top of home screen and then pulling down a second time to see the settings icon (a gear).

In settings:

1. System > System updates > click install > update should install - newer 8" tablets may start system update automatically

   1. takes about 15 - 20 minutes or more - simply says "optimizing applications" - screen may blank out during update

   2. need to keep checking

   3. will eventually display a restart dialog - click restart

   4. after restart - displays finishing system update briefly

   5. Check for system updates a second and third time - there will likely be cumulative updates that depend on the previous ones

2. Go back into Settings > Display > enable double tap to wake and lift to wake, set screen timeout 2 minutes, Lock screen > turn off notifications; on the newer 8” tablets this is in System > Gestures & Motions

3. System > Gestures > turn off quickly open camera

4. System > turn off Lenovo feature update

5. Security > Screen lock - set to none

6. Apps and notifications > Notification > turn off everything > set no notification mode on - set notification sound to none

7. Apps and applications > click on App info > disable (or uninstall where available) all apps, including Drive, Duo, Maps, YouTube, YouTube Music, Kid Space, etc. DO NOT disable Chrome, Settings, Google Play Services, Gboard (the Google keyboard), Google Go, or Lenovo Launcher as these may be needed later for troubleshooting.

8. Under Accessablility, disable TalkBack. If a user inadvertently enables TalkBack by pressing the up and down volume controls simultaneously, green boxes appear around controls, and touch functions stop working (this has happened at least once).

9. Disable Entertainment Space: tap and hold an empty spot on the home screen > Home Settings > turn off swipe to visit Entertainment Space

10. Move the Settings, Chrome and Clock icons to the secondary home screen (touch and hold, then slide them to the right) or drag them to the delete icon. The idea is to create a blank home screen so that the wallpaper will display cleanly

11. Enable developer mode: Setting > System > About Tablet > tap the "build number" 7 times - tablet turns on Developer Mode & Developer options become visible in Settings > System

12. Settings > System > Developer options > turn OFF Automatic system updates (automatic updates are not desirable since they may impact the app, and the latest updates should have already been installed in step 1)  ; turn on USB debugging

13. On the tablet newer versions, enable adaptive lighting in the screen settings and set the screen to not time out while looking at the screen.

14. Also on the 8" tablets, reduce text size in accessibility settings

if using Android Studio, connect a USB cable, enable USB debugging on the tablet (popup appears briefly - click OK). Android Studio should recognize the tablet and enable an install of the APK. Ensure the build variant option is set to "release" and not "debug".

The latest apk file for the Lenovo can also be downloaded (using Chrome) via this link: https://bit.ly/carpad_lenovo

If this procedure is used, find the apk file using the file app and click to install.

Note that on the Lenovo tablets, when the app initially starts up, the car list will appear with a large white gap at the top of the list. This will persist until the ADB command below is issued. At that point. restarting should cause the list to appear normally.

Run ADB commands from a computer connected to the tablet via USB (see the Samsung section above for ADB setup):

adb shell dpm set-device-owner com.turner.whit.revstabletv2/.AdminReceiver

Note: this command assigns ownership of the tablet to the CarPad application and makes it a kiosk-type application, which will autostart when the tablet is rebooted.

Also set wallpaper from computer using:

adb push carpad_wall_new.png /sdcard/

For the newer 8" tablets, use:

adb push carpad_wall_new_8.png /sdcard/

Note: the file must be in the current directory that your terminal program is using

Then use the file app on the tablet to set wallpaper image: system > storage > files >open with Files > just once > select wallpaper > move to downloads (or photos) - can also use tap on home screen and select wallpapers. Then touch home screen, wallpaper - select wallpaper > set as wallpaper. Another method is to find the file in the file app, then tap the dots in the upper right corner of the screen to select "use as wallpaper". The method used to set wallpaper from an image has varied over time with different versions of Android, so this may require some fiddling.

Issue this additional ADB command - this prevents system popups from confusing the user:

adb shell appops set android TOAST_WINDOW deny

Test the system by doing a restart and checking that the CarPad app starts and runs properly (note that the Lenovo tablets take a long time to initialize the app - at least 2 minutes after boot.

Escaping kiosk mode on the Lenovo tablet

In order to get to settings or make other changes to the tablet, press and hold the power button until the power off/restart popup appears. Touch and hold the restart icon until a second popup appears with the option of restarting in safe mode.  Select safe mode. The tablet will reboot and the app will not start, allowing full control of settings and other apps such as Chrome, which can be used to navigate to the download link at https://bit.ly/carpad_lenovo to reload the app. Note that when the tablet restarts in safe mode, it will also be in airplane mode, which must be manually turned off to re-enable WiFi. Note that if this step is skipped, the tablet will remain in airplane mode and the app will fail to populate after a restart.  Once changes are made, restart the tablet normally and the app should initialize.