Easy vehicle tracking with Particle Tracker One - PT1

I lived all my childhood in Mexico City's suburbs, a place where vehicle theft is an everyday issue. My parents still live there, and when my father told me he used his last savings to purchase a new pickup truck he needed for his work, I was a little worried. Criminals are extremely skilled at disabling commercial anti-theft systems so I wanted to use a noncommercial solution for knowing where the vehicle is at all times but also easy to install, maintain, and update.

I'm not well-skilled in software or firmware development, and I have no idea about servers. So the solution must be almost plug-and-play but not off-the-shelf. Price, as always, is a determining factor. I was also worried about giving third parties access to my data.

The ideal tracking system would have:

• A private server (but not maintained by me, ideally).
• The server tracking and database software running in the backend. Capacity for multiple users and multiple vehicles, live tracking, and history record.
• A web frontend, ideally a smartphone app.
• The tracking hardware installed on the vehicle. At least GPS and Cellular connectivity and backup power. Over-the-air updates are extremely desired.

For future development, I'd like to have:

• A way for sending commands to the vehicle (like power off the motor) via CANbus or OBDII.
• A way to escalate the solution for sharing the system for other family and relatives vehicles.

After a long search and evaluating lots of options for every part, I think I came to a good balance between effort, security, reliability, and personalization level. I have tested it for more than one month and now I'm sure is working and reliable, so I decided to make this tutorial for anyone who wants to replicate it. I will cut this tutorial into parts for "easy" reading.

This is the first part, we will set up the device, the cloud, and the tracking software.

Buckle up, this will be a long ride!

The hardware

The Particle Tracker One tracking system was the perfect fit. It has everything you need in a tracker and even a pre-compiled firmware ready to use! GPS, Cellular connectivity, WiFi, Bluetooth, RTC, thermistor, flexible power supply, and internal backup battery. All in a convenient IP67-rated enclosure! It also has an M8 connector exposing the internal CANbus controller, UART/I2C, or some GPIOs (one can be analog input). You can also power the device from that port instead of using the integrated USB-C connector. All the information you need to know is here.

The only downside it's that it has a literal "downside". You must find a way to put the device always facing the sky.

The Tracker One comes with a ready-to-use firmware called TrackerEdge. The firmware is open source so you can even modify it and add your custom functionalities.

When using particle products, you have access to certain amount of data operations and cellular data plan per month for free in your sandbox. You can always subscribe to a paid data block if you exceed that limit. Extra useful if you plan to escalate your system later. At the moment of writing this, is up to 100 devices, 100k data operations and 100MB of cellular data.

The particle console allows to see your devices live location but it lacks the storage and replay functionalities. That is because their policy of not store any personal data.

The software

Using the Traccar open-source software was extremely tempting, it has all the backend, frontend, and even the phone apps! Traccar offers its services in pre-configured servers at a monthly cost, but you can install it on your own server. Both, Traccar and the Particle console offers API and general purpose webhooks so it must be relatively easy to connect the particle console to the Traccar server and relay the location publishes.

The downside is that you need to have your own server running if you want to use it for free. An extra problem for me is that my internet service doesn't expose a public IP address so accessing remotely to a home server would be an issue difficult to overcome.

The server and cloud services

I once have read about the Oracle always-free tier service, maybe this was the chance to get a little dirty and learn again some Linux and how to get up my very first remote server. It says always-free right? It worth giving it a try.

So let's get started!

Setting up the Tracker One

There are two versions of the Tracker One. The LTE CAT1/2G/3G will work on most regions and the CAT-M1 will work only in North America. CAT M1 uses a lot less power so is a thing to consider.

Tracker One arrives in "Shipping mode" for saving battery. When you plug it with the supplied USB cable to your computer, the tracker will start. The leds will flash indicating the tracker is booting.

Next, we need to set up a particle account. After that we need to go to the setup web application. I really like to use Firefox but for the setup you will need to use Chrome or any Chromium-based web browser. When you hit the Get Started button, it will ask for login into your account if you are not logged in.

Next it will ask for the type of device to be configured. You need to select the device over USB option, next you´ll hit the select device and a popul will ask to select it. Look for the Tracker CDC Module. Click OK and continue.

The tracker will be put into "DFU mode" (cloud led blinking yellow). This causes the device to reconnect and identify itself as a different device. So the browser will ask you to select the device again. This is normal.

After that, the tool will determine if your device needs updates. Accept that. It takes a little while and you will see the status leds flashing in different patterns in the process. This will be the only time you need to do this using the cable. The next updates can be over-the-air!

When the update is done, you will be asked to select an organization and a product. The organization will be your sandbox. The products in Particle are a way to group devices with similar use for easing processes like updating all your fleet at once. Create a new product if you don't have one and give it a name.

Next you will need to name this specific device. It has to be unique.

Put your device near a window or in a area with open sky to allow the GPS to get satellite lock. When the GPS led gets solid blue, the device has a valid lock.

The cloud led will indicate if there is connection to the particle cloud with a solid cyan color and the battery led will turn yellow when the battery is charging.

Now you can go to your particle console and check for your device. In the left panel choose the products icon and then click on right product card.

Now on the new left panel, click on the location icon. You will see a map with your devices and their locations. You can zoom all the way in to look the exact location reported by your device.

On the upper right side of the console, there is a button for configuring fleet. Any change made there will be used for all the devices on your product. This configurations changes the behavior of the localization events, that will impact on the amount of used data and the life of your battery. You can learn more about this features here.

Getting and setting your free server

The user interface and the options on the Oracle cloud may change over time. I used this tutorial as reference making minor changes, so expect to follow the same procedure but maybe with little differences.

First go to the Oracle page and make a new account and go to your mail inbox to verify your account by clicking the link they sent. Next it will ask you extra personal information. Enter it and choose "Individual" under "Customer Type". Remember the cloud account name, the mail used and your password. We will use it later.

Next, you will need to enter you payment information... I know. Nobody wants to do that, but Oracle promises you to never do extra charges without you explicitly going to your account and activate the paid services. So far, I got my system working for a couple of months and that promise was honored.

Once you are registered you can access with your credentials to your Cloud Console. Oracle is extra secure and it will ask you to use it's authenticator app to be sure it's you. Give it a chance and go with this.

You will be presented to your cloud console.

We will now create a new remote server. Under the "Get Started" tab look for the "Create a VM instance" option. You'll see that the option is marked as always-free elegible.

Give your server a name, leave the compartment in root and go to "Edit" next to "Image and shape".

Here you can configure your virtual server and the OS it will run. You can select any combination you want as long if still marking it as "Always free enabled", but be aware that the nexts steps may differ on configurations other than the used here.

As some OS will not work on some shapes, first select your shape. Shape refers to the "hardware" (virtualized) you are choosing for your server. I used a Virtual Ampere VM.Standard.A1.Flex with 1 core and 6Gb RAM. I don't expect to this server to have a heavy workload so I chose to use the minimal.

Please note that the Ampere is ARM based. If you use any other shape, write down the architecture you are using. This will be important later. Accept the changes and now go to change image.

Here you can choose any OS you like for your server. The page will warn you if the OS selected is not compatible with the shape or if it's not candidate for the always-free program. I used Canonical-Ubuntu-22.04-aarch64-2023.07.20-0 because I'm a little more confident with Ubuntu and because "aarch64" means it works with ARM based architectures.

Next go to Edit Networking.

If this is your first server, you'll need to create a new cloud virtual network. Choose that option, also mark "create new public subnet" and "Assign a public IPV4 address". Everything else can be the default and proceed to the next section.

The recommendation is to generate a new ssh key pair. Save both keys on your computer at this precise point. These are the credentials for access your server. Store them in a safe place and make a backup just in case. If you lost them, you lost the access to your server.

Finally, unmark all the checkbox on boot volume section. and click on "Generate". It will redirect to your server status page. The Icon on the left will be yellow with a message saying the server is provisioning. Yo will need to wait until the icon turns green. That means your server is up and running.

You can remote start, stop and reboot your server at will using the buttons on this page.

Under "Instance access" section you will find the username you will use to log in your server and the public IP address of your server. Write it down.

Now we need a way to access our server. This is made by SSH protocol. Depending on the OS your are using on your personal computer you need to use a different SSH application.

On windows I failed to make work PUTTY, the standard software for SSH. I ended using powershell. On unix systems, is common to have ssh already installed. Also, you need to use the keys downloaded previously but you need to change their file permissions. You can check this doc on details on how to do this on every OS.

We are ready to install software! First go to your console and type:

ssh -i path_to_key/file.key username@ip_address

Where:

• path_to_key/file.key: is the path to where you key file is stored on your computer.
• username: the username you wrote it down
• ip_address: your server public ip address

If everything went well, you will be greeted by the login message:

Note the "$" on the prompt, it says you are logged as user. All the next steps must be done with root privileges, so type:

sudo -su root

Your prompt must change to "#". If for any reason you get logged off, remember to enter as root again!

Installing the Software

This was the more difficult step for me. Any documentation on the web is prone to be obsolete and outdated quickly so this part may be change over time.

First things first, update the repositories index.

apt-get update

The official documentation for installing traccar completely overlook the java installation. Do this before attempt install traccar and you'll save hours of frustration if you are novice doing this.

Install java.

apt install default-jre

Check if java is running.

java -version

You will see the current version installed:

Install the Unzip utility and MySQL Server.

apt update && apt -y install unzip mysql-server

Set a password for the database server, give privileges to the root user and create the Traccar database. Do not edit, paste as it is.

mysql -u root --execute="ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'root'; GRANT ALL ON *.* TO 'root'@'localhost' WITH GRANT OPTION; FLUSH PRIVILEGES; CREATE DATABASE traccar;"

Download the latest installer for Traccar.

You will save hours of frustration just by looking at the right version for your server. This is not specified in the official steps. For the Ampere server it has to be the traccar-linux-arm64-x.x.zip version!

wget https://www.traccar.org/download/traccar-linux-arm64-5.9.zip

Unzip the traccar installation file and run it.

unzip traccar-linux-*.zip && ./traccar.run

Update the Traccar configuration file to point to the database. Paste as it is.

cat > /opt/traccar/conf/traccar.xml << EOF
<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE properties SYSTEM 'http://java.sun.com/dtd/properties.dtd'>

<properties>

    <entry key="config.default">./conf/default.xml</entry>

    <entry key='database.driver'>com.mysql.jdbc.Driver</entry>
    <entry key='database.url'>jdbc:mysql://localhost/traccar?zeroDateTimeBehavior=round&amp;serverTimezone=UTC&amp;allowPublicKeyRetrieval=true&amp;useSSL=false&amp;allowMultiQueries=true&amp;autoReconnect=true&amp;useUnicode=yes&amp;characterEncoding=UTF-8&amp;sessionVariables=sql_mode=''</entry>
    <entry key='database.user'>root</entry>
    <entry key='database.password'>root</entry>

</properties>
EOF

Start the traccar service.

service traccar start

If for any reason you need to see the traccar logs, you can use.

journalctl -u traccar -f

The logs may differ, the important part is look for no error messages. At this point Traccar is running! You can exit the logs with CTRL+C

Opening the server ports

Sadly, we are not done with our server. By default, both Oracle and Ubuntu have the necessary ports closed. We will need to open them on both to access traccar and its API from outside.

• For the webhooks we need to open port 5055
• For the web app and general services we need to open port 8082

On yourserver

SSH to your server (use root privileges) and use any editor to modify the file /etc/iptables/rules.v4 I'm using nano to edit the file.

nano /etc/iptables/rules.v4

Look for the line that already has the port 22 open (you are using SSH on port 22 so it might work) and copy it changing the port number for 8082. Repeat for 5055.

You can add a line starting with "#" to add comments and find your custom lines easier. It will look like this:

In nano: CTRL+S for save, Y, ENTER, CTRL+X for exit.

Update the port rules by running:

iptables-restore < /etc/iptables/rules.v4

On the Oracle Cloud

Log again in your Oracle Cloud Console. Look for the hamburger menu icon on the top left, next to the Oracle Cloud logo. Click it and select "Networking", next click on "Virtual cloud networks".

Click on the name of the virtual network for your server. If you only have one, it will be the only name to click on the table. It will open your network panel. On the left panel click in "Security lists".

Click on the Default Security List on the table. On the next screen click on "Add ingress rules".

Fill the information:

• Source type: CIDR
• Source CIDR: 0.0.0.0/0
• IP protocol: TCP
• Source port range: All (leave unmodified)
• Destination port: 8082
• Description: Something that remembers you the use of the open port

Save changes and repeat for the 5055 port.

At the end you will have something like this:

You can use this tool to check that your ports are open. You'll need the public ip address of your server.

Now is time to access traccar! Go to your browser and type the ip address of your server, adding ":8082" at the end.

You will be greeted by a page asking for creating your admin account. Create it and log in the system.

The interface will look like this, but with the vehicle list empty. I have two already configured. Later you can manage your system at will. First we will link our Particle cloud with the traccar server.

Linking Particle and Traccar

We will need to create an access token to give permissions to the particle cloud to talk to the server. In your traccar console click on the gear icon, on the bottom on the vehicles list.

On the next screen click on "Preferences" on the left panel. Look for access token and select a expiration date for that token. You can go very far on time to be sure it will not expire in the middle of a rescue search!

Next click on the arrows to generate a new token. Copy the full text and store it. This token along the mail address you used to setup your traccar account will be your credentials for webhooks. Click save.

We will now create a webhook on the particle console to send the location information of our Tracker One to our traccar server.

By default, the TrackerEdge firmware sends a series of data to the cloud every time the location event is triggered. The event can be triggered externally (more on this later) and will be triggered internally, depending on the product fleet configurations set in the console.

The default location event is named "loc" and the data comes in pairs of tags and values. Some default tags are:

• "PARTICLE_DEVICE_ID" - The device id on the particle console
• "loc.lat" - Latitude
• "loc.lon" - Longitude
• "loc.time" - The time mark of the location event (gathered from GPS)
• "loc.alt" - Altitude above sea level
• "loc.spd" - Calculated speed (GPS)
• "loc.hdop" - Horizontal accuracy
• "loc.batt" - Internal battery level
• "loc.temp" - Internal temperature
• "loc.hd" - Calculated heading (GPS)

You can pass any data to traccar, making possible to send status vehicles like if it's on, the RPM reported by the CANbus, etc. For this you have to modify the stock TrackerEdge firmware to report those values along the location event. Some tags will be automatically interpreted by traccar if you send it along the right label. Here is a discussion about that topic in the traccar forum.

Go to your particle console, enter to your product console and look for the "Integrations" icon on the left panel. Click on "Add new integration".

Next click on the "Webhook" option and you will see a form to fill with the webhook data.

• Name: Any name that identifies your webhook.
• Event name: loc <- This is the event name published by the Tracker One
• URL: http://traccar_server_ip_address:5055
• Request type: POST
• Request Format: Web form
• Form fields: Expand "Advanced settings", click "custom" and you will see two columns. On the left you put the label (or field name) of the event variable specified in the right. Traccar will receive this data and sort it by the field name. Add as many rows you need and fill it with the data you want to pass to traccar. Use the example below:

• Query parameters: Leave blank
• HTTP basic auth: here you put your traccar mail and access token
• HTTP headers: Leave the default values
• Webhook responses: Leave the default values
• Enforce SSL: No

Your webhook will be ready and you will presented to a summary.

Don't try the "TEST" button! By clicking it you will always receive an error because it sends an empty request to the server and you will see errors and wasting a full hour hour trying to understand why it's not working!

We will test te webhook later. First we need to setup the new vehicle in Traccar.

On your traccar console, hit the "+" icon next the search bar. You will be redirected to the devices configuration. We will create a new device and link the Tracker One publishes to it.

Fill the next info and click save:

• Name: Any display name you like for the device (ie. the car model or who drives it)
• Id: The device id you Tracker One has in your particle console. Marked red in the image below.

On your traccar console you will see the new device added but offline. Traccar is waiting to get a publish from it. We will force a location event on the Tracker One to test all our work.

On your particle console, go to devices and search for your Tracker One. Click on its row to manage it.

On the new screen, scroll down until you find the "Functions" section on the right panel. You'll see a "cmd" function. In the argument field, write:

{"cmd":"get_loc"}

Click on "call". This will enforce a location event, sending the data to traccar through the webhook. (You can see the other commands available on the default TrackerEdge firmware, here).

Finally!

If everything is well configured, by pressing the call function button, you will see your new vehicle online and geolocated on the traccar console. Success!!

Bonus

You can download the traccar manager app to your phone to manage and see your vehicles anywhere you go!

Next steps

So far we have the backbone of our tracking system working.

For the next part I will be installing this on my dad's vehicle and I will take a look at the communication buses of the truck.

The third part will consist of modifying the firmware to have data from the on-board computer and send commands to the vehicle.

So stay tuned!