M5Stack GPS Logger

I love to ride my motorcycles! When I go out riding, I typically plan my route using ITN Converter and transfer the itinerary file to my TomTom Rider 1 gps. Now while following this planned route, there's more often than not deviations along the way and the actual ride can vary quite a bit from the planned route.

So the initial thought behind this project was to log the GPS latitude and longitude position information every 10 seconds into a GPX file (the GPS eXchange Format) that I could retrieve later and view the actual ride in ITN Converter (which is also capable of reading these files). Sounds pretty simple, right? At the time when I started the code, I had a basic black M5Stack and I was going to use an A9 Pudding board which is a GSM/GPRS/GPS development module. I would use the module's GPS functionality for the position logging and the GPRS to post my current location to dweet.io so that my friends and family could see where I am when I leave on long trips.

Prototype

Over the period of May 2018 to April 2019 there's been three complete re-writes of the code and changes to the hardware along the way. There always seems to be something I can add or do better in the code or a weird undocumented condition with the A9 Pudding board that caused unwanted behaviors with the software.

What I'm presenting is the forth and simplified re-write of the code that no longer uses the A9 Pudding board, but rather the M5Stack and it's GPS module. The code was written with two possible compilation options. First using the M5Stack-Core-ESP32 as the board type and the second using the ESP32 Dev Module. If you are using the second option, you will need the components that are marked "Required if building without M5Stack" in the Things section.

Where to Start?

The first thing you need to do is to get the API keys required in order to run the software. The software needs two API keys, one from OpenWeatherMap.org and the other from Google.com. They are stored in a configuration file in the root directory of your SD card, the file name is Config.txt and contains all the setup parameters needed for the application.

Let's start with the simpler of the two, OpenWeatherMap.org... They have created a simple three step process in order to use their services, see steps here. Of these three steps you only need to do step one. Signup and wait until you get the email from them containing the API key. Once you have this API key, add it to the Config.txt file in the root directory of your SD card under the label "OWappid=".

Next you'll need to get the Google API. On July 16, 2018 a new pay-as-you-go pricing plan went into effect for Maps, Routes, and Places. They no longer have the free API key. But worry not, you get a $200 monthly credit that will cover the usage you'll place on Google's services. They've added this new billing method to most likely keep the riff-raff out of their services. If you not prepared to put up a credit card, you're probably not really serious about using their services.

Start here and read the Frequently Asked Questions section for more information on how the new billing works. You will need to check the Maps and Places checkbox. Next it will ask you to select a project, the API key is generated by project. Enter a project name such as "M5-Tracker" or "ESP32-Tracker" for example. Next it will ask you to setup the billing account for the project, follow the steps and once completed it will generate the API key and show it to you in a dialog box. Copy this key and add it to you Config.txt file under the label "GoogleAPI=".

Compiling the Code

Once you have the API keys you can download the code from GitHub and select which board you'll use for the project. As mentioned earlier, the code will compile with either the M5Stack-Core-ESP32 board or the ESP32 Dev Module.

Of note, I am using;

• Arduino version 1.89
• Espressif's ESP32 board manager version 1.0.2
• M5Stack library version 0.2.7

Make sure you're up to date with the libraries and board manager versions before compiling the application.

Next you'll need to install two additional libraries;

• Time library by Paul Stoffregen. GitHub here.
• TimeZone library by Jack Christensen. GitHub here.

TimeZone Change

Once your environment is up to date and you're ready to compile, you need to possibly change some code depending on your time zone. The timezone is defined in the code as;

//
// Eastern Time Zone rule 
//
TimeChangeRule myEDT = {"EDT", Second, Sun, Mar, 2, -240};  // Eastern Daylight Time = UTC - 4 hours
TimeChangeRule myEST = {"EST", First, Sun, Nov, 2, -300};   // Eastern Standard Time = UTC - 5 hours
Timezone myTZ(myEDT, myEST);

You'll find these at line number 115 to 120 of the code. If you live in the Eastern timezone, you have nothing to do. Otherwise change the code accordingly.

Config.txt Setup

Instead of hard-coding the application's configuration values, I decided to use an external file where I could edit the values when needed without having to re-compile. This file is named Config.txt and is stored in the root directory of the SD card. There are several fields in this file which need to be set in order for the application to properly configure your device. Let's look at each field in detail.

//
// Configuration file for ESP32_Tracker
//
UserName=        Your name, alphanumeric, max 32 characters
Motorcycle=      Your motorcycle type, alphanumeric, max 32 characters
Mileage=         The mileage on your motorcycle, numeric
OilChange=       The mileage of last oil chage, numeric
DweetName=       Name used to post to dweet.io, alphanumeric, max 20 characters
HomeLatitude=    Your home latitude, numeric
HomeLongitude=   Your home longitude, numeric
HomeRadius=      Distance from home to be considered home, numeric
CellWiFi=        Cell phone hotspot name, alphanumeric, max 20 characters
CellPass=        Cell phone hotspot password, alphanumeric, max 20 characters
HomeWiFi=        Home WiFi network, alphanumeric, max 20 characters
HomePass=        Home WiFi password, alphanumeric, max 20 characters
HostName=        M5Stack hostname, alphanumeric, max 20 characters
HostPass=        Hostname update password, alphanumeric, max 20 characters
DailyShutdown=   Shutdown M5Stack on a daily basis, fixed, "TRUE" or "FALSE"
MinDailyDistance=Minimum distance travelled in order to keep GPX file, numeric
LightBox=        Display pictures in a lightbox, fixed, "TRUE" or "FALSE"
//
// Define OpenWeatherMap.org and Google API credentials
//
OWappid=         Your OpenWeatherMap.org API key, alphanumeric, max 64 characters
GoogleAPI=       Your Google Maps API key, alphanumeric, max 64 characters

The fields that are mandatory are; HomeLatitude, HomeLongitude, HomeWiFi, HomePass, OWappid and GoogleAPI

UserName and Motorcycle are fields that get written to the daily GPX file.

Mileage and OilChange are used to calculate the mileage to go until your next oil change. I am religious about doing them every 5000 Km. Even when on a long trip, I'll find a local motorcycle shop to do it. If not set you will get incorrect readings on certain screens.

DweetName is used to post to dweet.io your current location while on a road trip. You would enable your cell phone hotspot, wait for the M5Stack to connect to it and then start your ride. Every 30 seconds it will post your location. You would provide the following link https://dweet.io/follow/DweetName (DweetName being the name you entered) to your friends and family and they would see where you are on your trip. Last fall I did a tour of Eastern Canada for 10 days and my cell phone usage barely went over 200MB of usage, on a 6GB plan.

HomeLatitude and HomeLongitude are needed to calculate the distance from home. You can get these values from https://www.google.com/maps.

HomeRadius is used to determine a radius, in meters, from home that you'll be considered home. Mostly used for reporting in the web server. If left blank it will default to 25 meters.

HostName and HostPass are used for the Over The Air (OTA) program update from within Arduino. If left blank, they will default to "M5-Tracker" and "admin".

MinDailyDistance is used during a daily scan of rides you did so far this month. If the distance on any given day is less than this value, in kilometers, the daily GPX file (or ride route information) will be deleted. So if you're travelling each day to work on the motorcycle, doing 22 Km and you don't want these rides to appear in the monthly ride calendar, you would put a number larger than 22 in this field. If left empty, it will default to 5 Km.

DailyShutdown is used to put the M5Stack in deep sleep mode when it hits midnight. This is used full to save battery power. When in deep sleep, the M5Stack only uses 0.02 MA and will not drain your battery. If left empty, default is "YES".

LightBox is just to select which method to display pictures on a web page. If set to "YES", a lightbox method of diplaying images will be used, otherwise a popup method. Default is "YES" for a lightbox.

Here's an example of a valid Config.txt file except for the API key...

//
// Configuration file for ESP32_Tracker
//
UserName=Claude G. Beaudoin
Motorcycle=2014 Suzuki DL650A ADV
Mileage=63012
OilChange=61894
DweetName=SeeMeHere
HomeLatitude=45.557579
HomeLongitude=-73.447380
HomeRadius=25
CellWiFi=CGB-CELL
CellPass=cellpass
HomeWiFi=VIDEOTRON3587
HomePass=homepass
HostName=M5-Tracker
HostPass=admin
DailyShutdown=YES
MinDailyDistance=5.0
LightBox=YES
//
// Define OpenWeatherMap.org and Google API credentials
//
OWappid=YOUR_API_KEY_HERE
GoogleAPI=YOUR_API_KEY_HERE

Other Files in Root Directory

They are image files for the M5Stack startup, shutdown splash screen and an example of a favicon.ico used by the web server. The splash images PowerOn.jpg and PowerOff.jpg must have a resolution of 320 pixels by 240 pixels and must be in a jpeg format. There is also the M5Stack logo you could use as the power on image.

Weather Icons

You will need to copy the /Weather directory to the root of the SD card as this stores all the weather icons from OpenWeatherMap.org that are used by the M5Stack to display the current weather and a 3 day forecast.

Okay, Show Me What It Does

Below is a series of screen captures from the M5Stack showing you some of the options available. In the Main Screen you can see the distance you've traveled today, your actual riding time, your average speed and maximum speed, the distance home and some GPS info, number of satellites in view and altitude.

One screen that I find very useful is the daily weather screen because it gives me today's sunrise and sunset times. The sunset time I keep in mind because I like to arrive and have my tent setup before it gets dark outside. So knowing this allows me to better plan my ride for the day and arrive an hour or two to my campsite before it gets dark.

Once the application is compiled and downloaded to the device, you'll be able to view your monthly travel web page. This page will be displayed when the device is connected to a WiFi network and your web browser is connected to the same network. Thus the reason for the two WiFi networks in the Config.txt file.

At startup, it will allow you to select which network it will use, your cell phone network or your home network. This is useful when you want to add riding notes, pictures and medial files to rides later. The IP address of the web server is displayed on the Main Screen of the M5Stack when connected to a network.

As you can see from the example images, the web server has many pages that it can display and you can edit the content of the Daily Ride page making this project indispensable for the serious motorcycle enthusiast who likes to track and log their rides.

I've been doing motorcycle camping weekends and long trip for a while now and I wish I had something like this in the past. Now I bring my tablet and complete my riding notes while there's still fresh in my memory and add the media content (pictures and videos I make) when I get back home.