Improving Karoo through the use of Android Apps and how to get started.
Sun Jul 01, 2018 3:07 pm
I’m an engineer, but I’m not an Android expert or even an Android novice. So I worked through this all with a friend on facebook (thank you to Ket Pang on the Karoo Facebook Users Group) to get mine working. I documented how that all works below and it may be useful to others. There are no guarantees of accuracy, security or that it even works. By following what I did, it's your risk and there are no guarantees.. I'll keep at this and update it as I learn more.
There are typically two problems that people run into when they attempt this. Both are simple but are not obvious.
Micro usb cables come in two different flavors - (a) charge AND sync cables, and (b) charge only cables. You MUST have a charge and sync cable. Typically these come with phones, cameras or any other device where you have to move data back and forth from the device to your computer. If nothing else, you can order one for very cheap on Amazon. THIS IS THE ONLY TYPE OF CABLE THAT WORKS for obvious reasons. The "charge only" cable lacks the data connections in it to transfer data. If you use this, your computer won't even know the Karoo is attached.
This is because Unix is very particular about it's directories. If you have used unix before and have not had such issues, it's because someone set up the PATH variable to take care of that for you. It's not a big deal, instead of typing "adb" type "./adb" from the platform-tools directory. The "./" the precedes the "adb" command basically means "the file found in this directory.
All my mobile devices come from the Apple ecosystem so I have limited to no experience with Android from a user perspective. I wanted navigation that works well on the Karoo for an upcoming tour we’re doing that will require good mapping and the ability to manage it entirely from mobile devices. I wanted to use the Karoo since it’s just a better display.
The basic idea here is to do the following:
- Get the tools and set them up.
- Get an app store, an app switcher, and a launcher downloaded and installed on the Karoo.
- Get Firefox (internet browser) installed on the Karoo so you can install the Amazon app store.
- Use the two app stores you will load to set up your switcher and download your apps.
- Get your apps set up on the Karoo properly. This includes setting the proper permissions on each app that you side load.
If you follow the directions below, this will get you set up with a way to launch your Karoo software to start and manage a ride, a fast app switcher to you can swipe to your side loaded apps quickly like riding and back to the Karoo data screens. The launcher and app store to get the switcher app are available directly from the internet downloads. I chose to install my navigation apps and others through the Amazon App store that I installed on my Karoo. The Amazon app store is downloaded and installed via Firefox. Firefox is downloaded and installed via the APKpure app store that is a direct download and installation via an internet download. So you go and first get the APKpure app store and Nova Launcher via downloads, install them on your Karoo. Then you use APKpure to download firefox to get the Amazon app store loaded (http://www.amazon.com/androidapp access via firefox). When that is done, log into the Amazon app store and set the rest up. Once you have that complete, I offer a set of scripts to back it all up and bulk reinstall it back on your Karoo elsewhere in this project. At that point, it takes just a few minutes to set up a newly reset or brand new Karoo.
When you add system updates of the Karoo software, they do not disturb your side loaded apps (or vice versa). The Karoo software is nothing more than a collection of Android apps and their own launcher. You are setting up your own launcher that can launch the Karoo launcher. From there, the Karoo apps run in harmony with the android apps that you side load. It's that simple.
Both of the app stores that you load (APKpure and Amazon) allow you to install updates to your side loaded software. Just go to each app store on your Karoo and select updates.
Most of the side loaded apps will need to have the permissions setup (storage, location etc...). You do that by going into the Nova Launcher and long pressing on the app icon. You will be given a contextual menu. Select "app info" and grant the permissions. It's generally best and most efficient to do this right after installation and before running the app. You will likely need to do with every app that you install.
Here is what I did:
- Download the Android debug bridge (adb hereafter) for the mac here: https://developer.android.com/studio/#downloads and install it on your system.
- On your Mac, open the Terminal application which is found in your utilities folder.
- Go to the folder in which the adb was installed. For simplicity, just do everything here from folder. You can get more creative and set up shell environment variables for your particular system. But here, I’ll just refer to the app in this folder and any downloaded apps you have from your download folder.
- Connect the Karoo to your computer with a USB cable that has full connections. Many USB cables are only useful for charging. If you cannot connect in later steps, make sure to try other cables. If that doesn’t work, then install the Google USB drivers from the link above in step #2.
- Boot up the Karoo.
- Go to the Settings app and scroll down to “About”. Scroll all the way to the bottom until you find “Build Number”. Tap on this 7 times with your finger. This will take you to “Developer Mode” and Karoo will tell you that this is where you are headed after about the first three taps.
- Once in Developer Mode, in Settings, scroll down to the "Developer Options" choice and tap it. Once in that choice, make sure that the "Developer Options" switch at the very top is "on.".
- Scroll down to "USB Debugging" option and turn that switch on. This enables your mac (or your PC for that matter) to talk to the Karoo over the USB cable.
- Once you are in developer mode and have completed these steps, go back to your Mac.
- On your Mac, invoke the adb in the terminal by typing “./adb devices” (yellow arrow). This will ask for the android devices attached to your computer. See:

The red arrow shows that the Karoo is attached to your Mac where the string in front of the word “device” is the identifier for your Karoo. - Download APKpure which is a source for Android app store software from https://apkpure.com.
- Install APKpure onto your Karoo by locating the apkpure package which you just downloaded onto your Karoo. To do this you type “./adb install . It should look something like this (https://www.dropbox.com/s/df4pkh46oz0d1 ... 2.jpg?dl=0):
-
The first line is the line that you just typed in. Hint: In order to get the file name into the Terminal command, locate the file in the finder and just drag the file onto the command line. The MACOS will automatically put in the filename for you and the file will remain on your system where it was before. That makes it a lot easier to avoid having to navigate all the unix file naming conventions especially if you have spaces or characters in the filename path.
-
the second line is the adb transferring the file to your Karoo.
-
the third line is the name of the file and where it is located on your Karoo in the Android file system.
-
The third line with the word “Success” means that you successfully transferred it to the Karoo.
-
Repeat the process for the Novalauncher. You can download the Novalauncher here: http://novalauncher.com. There is a link that says “Direct Download APK”. Use that.  Once you have apkpure NovaLauncher loaded on your Karoo, go ahead and reboot. As the Karoo reboots, it should give you the option to select the launcher. You should have the option to run the launcher always or just once. Until you get it all set up the way you want, probably just select “Just once” but select “Nova Launcher”. Just plain “Launcher” is the Hammerhead launcher that gives you the familiar Karoo startup screen.
-
Use the Nova Launcher to create a widget for the Hammerhead Launcher. To do this, go to the Nova Launcher screen, find a blank spot and press. Select “Widgets” at the bottom. Like this (https://www.dropbox.com/s/48zazc13b3rks ... 4.jpg?dl=0) and (https://www.dropbox.com/s/bmdzq93fwq5mh ... 5.jpg?dl=0):
-
This will give you a menu. Select the Novalauncher icon with “Activities” underneath. This will bring up a list of possible widgets. Scroll down until you find the Hammerhead logo with “Launcher” next to it (https://www.dropbox.com/s/3coj0a3e20evq ... 6.jpg?dl=0).

Your screen will now look like this (https://www.dropbox.com/s/oluka6eph4pxt ... 7.jpg?dl=0):

To run the Karoo software, select the Hammerhead logo from your home screen.
From NovaLauncher, run APKpure app. In there, search for Switchr - an gesture based app switcher. You can read about this separately, but it gives you a great way to quickly switch between apps you may want to use on your Karoo.  I also loaded the Amazon app store on my Karoo to get access to some paid apps. From this, I paid for Osmand+ which is the unlimited map and overlay download of Osmand as well as RadarScope (see below). Google for Amazon app store and install it the same way you did APKpure.
Apps I have on my Karoo that make it a great cycling experience
- Switchr - an app that allows you to quickly switch between any app you’ve loaded and the Karoo software while riding.
- SoundWave or PodCast Player: listen to podcasts while you ride.
- Dropbox: Allows me to download files into various apps using my dropbox account.
- Osmand: Open source and free navigation program including audio turn by turn directions. You can download waypoints and gpx files into this for routes through dropbox. Works very well. (http://osmand.net). I purchased the paid version from the Amazon app store. Since this is frequently updated, in addition to more features, it also keeps the app up to date through Amazon's update mechanism. Osmand has the most detailed maps and you can add topographical lines, hill shading etc...
- Komoot: Komoot is a excellent navigation app that gives the best turn by turn directions. When you import a gpx file, it will fit it to the nearest roads and generate turn by turn directions that include road names. Highly recommended.
- Radarscope: Color weather radar up to date within 1-2 minutes. I can see precipitation and how it impacts my ride. To do this, you will either need an installed SIM card (haven't tested) or set up your cell phone as a wifi hotspot and make sure Karoo is connected to it while you ride. This is a paid app but excellent.
- MyRadar: Another weather radar app but free. This is the best while riding. If you give it access to your location it will track your location and keep the radar map center on where you are. If you have a sim card in your Karoo or connect it through your phone as a hotspot, this will give you live weather radar on your Karoo tied to your location. Very handy for riding around precipitation.
- Bluetooth Audio Widget Free - as of the 1.15.216.3 update on 30 August 2018, the Karoo video app was removed and with it the ability to pair and manage bluetooth headsets or speakers. Adding this app (or one similar) replaces that functionality and is an actual substantial improvement over the video app. This is available on the Amazon app store. With this, it is possible to get audio turn by turn directions via Osmand or Komoot from your Karoo.
- ES File Manager: I use this back up my applications as packages into a folder for the backup scripts available in this project.
- Zello: Zello is a walkie talkie app that runs over cellular data. If you pair headphones with the Karoo and get one of the bluetooth PTT (push to talk) buttons compatible with Zello, you can use your Karoo as a means of communication to your group. You will need to be in a cellular data area and have either a SIM card installed or the Karoo connected to your cell phone set up as a wifi hotspot.
All of the apps listed above are available via the Amazon App Store. You install the Amazon App Store by going to http://www.amazon.com/androidapp in firefox on your karoo and downloading it. You can then install it directly from firefox's download folder.
As of about 5 July 2018, it looks like there is now a free version and a paid version. The free version is named "Osmand" and the paid version is named "Osmand+". The free version limits you to about 7 regions you can download to the unit. In the USA, a "region" is roughly a state. Some countries are regions, in some countries the larger regions are the regions. You are also not able to download contours and "hillshades" that give your map some 3D-ish quality and let you know a bit more about the terrain. To get the paid version (which I did), I downloaded the Amazon store and purchased it there with my Amazon account. Cost for the paid version is about $9 USD or so and the contour plugin was about another $4 USD. You can also download the free version and when you hit the 7 regions downloaded, you can delete it and reinstall it and get 7 more regions. Just seemed easier to me to pay the $13 and help them finance continued development.
What I do now is I create folders of my GPX files on Dropbox and just open them as I see fit for the given set of routes I'd like to use. Clicking on them drives them into Osmand/Osmand+ and everything is ready to go.
You can pair headphones and bluetooth speakers to the Karoo by going to the Karoo “Video” app and pairing the headphones there. Once you do this, you will be able to listen to podcasts, get spoken turn by turn directions etc… on the Karoo. I have also paired this very nice and inexpensive BT speaker to my Karoo. This speaker is tiny and has an excellent clip so it will clip to my jersey. It's about $15 on sale and gives excellent sound and is perfect for turn by turn audio navigation cues. I would love to see Hammerhead set up with audio cues for their device in general through bluetooth. This sort of product would be awesome. https://www.polkaudio.com/products/boombit
From system update 1.5.216.3 which was made available on 30 August 2018, Hammerhead has removed the Video app. This is where you paired your bluetooth devices in the past. In order to manage, pair and use your bluetooth audio devices you will need to side load one of the many Bluetooth Audio apps available for free on many of the Android app stores. I use the “Bluetooth Audio Widget free” that is available for free on the Amazon app store. When you start this app, you can pair devices, select the bluetooth audio profile to use for them, adjust the volume boost etc... It’s a big improvement over the video app for managing bluetooth and an overall improvement. Using this widget, I have successfully pair my Apple AirPods, my Aftershokz Trek Titanium and other bluetooth headsets, bluetooth speakers and other audio accessories without drama or difficulty. The widget exposes the standard bluetooth control panel in Android as well as providing an adjustable audio boost capability.
Note that in system revs beyond 1.17 or so, Hammerhead has re-enabled the ability to add bluetooth audio directly in the Karoo settings app. There is a bluetooth control panel in the settings app but you can also include the bluetooth control panel discussed above - it provides a little more functionality and is helpful too. Also note that Hammerhead has enabled both the audio and the microphone android profiles so you can now use applications that require access to the microphone. For example, we have used Zello as a walkie talkie app to coordinate rides using our cellphones and an earbud. You can now do this all with the Karoo and a headset/earbud and it works great provided you have either a sim card installed or have the Karoo connecting to a cell phone on your person that is set up as a wifi hotspot to give access to the internet.
You need to follow the process above to bootstrap yourself into a configuration once. Then go to the Amazon app store, load ES File Manager, back up your APK's to the app folder provided by ES File Manager. Go to the settings in Nova Launcher and back them up. Once done, download the two scripts included in this project and put them in ~/platform-tools on your Mac. Change the permissions on both files by using the chmod command (+x is the switch). and then execute the backup script first.
This backup script will put all the apps you backed up with ES File Manager into folder at ./Karoo/apps. It will - specifically - back up Osmand data and maps, your Komoot data and your Nova Launcher backup folder.
Should you ever have to reset your Karoo (you will) and need to reload all this stuff, use the install script run from the shell. This will then install all the apps you have backed up and it will copy down all of the Osmand and Komoot data so that when you open them up (Komoot requires a log in), everything will be as it was.
Before you open any apps, you will need to log into the app stores you downloaded and then go in using Nova Launcher and grant permissions to all of the apps including Nova Launcher. Once that is done, run the apps as you see fit.
Before I wrote these scripts, it took about 45 minutes of painstaking work to re-load all my apps and then I had to babysit the Karoo while all the maps slo-o-o-o-owly downloaded over the internet directly into Osmand. With this, and using the high speed USB 2.0 ports on my Mac, this whole set up was pretty much ready to go in about 15 minutes including logging into apps and granting permissions. Best part is that for about 11 minutes of that process, I could go and do something else.