Cloud Setup

The software’s cloud segment consists of two primary components:

Traccar GPS Server
EMQX MQTT Broker

The embedded software establishes communication via MQTT-SN with the MQTT-SN Gateway within EMQX MQTT broker. Each time a device transmits a message to the MQTT-SN gateway (over MQTT-SN protocol), a predefined rule is activated. This rule extracts pertinent device information like location coordinates, battery percentage, GPS accuracy etc and subsequently relays the message to the Traccar REST server utilizing the HTTP protocol.

You would run the following commands on the host computer you wish to host the FindMyCat cloud services on. Most people would likely use a Cloud Provider (see Cloud providers) but it is also possible to self host.

Using automated script (recommended)

The cloud repository contains a findmycat.py wrapper around four commands: start, setup, verify and destroy. The script is provided for convinience but if you prefer to install it with Docker or manually, please follow the instruction in the relevant tabs.

Pre-requisites

Docker Engine Installed (Tested on Docker version 29.7)
Docker Compose V2 (Tested on v5.4)
Python 3.8 or newer.

Clone Cloud repository


git clone https://github.com/FindMyCat/cloud.git
cd cloud

Start the stack

Brings up Traccar and EMQX, waits for both containers to come online.


./findmycat.py start --emqx-password 'something-long'

--emqx-password replaces the EMQX dashboard’s default admin/public login.

A successful run looks like the following:

Create the Traccar admin account

Traccar does not ship with a default administrator account, to create one, open its web UI on port 8082 and register. The script provides a reachable URL for convinience, you can click to open the Traccar UI.

Configure the device and EMQX rule engine

Registers the device id in Traccar, creates the EMQX webhook resource, and creates the rule engine rule. Use Traccar credentials you used to create the admin account in step 3.


./findmycat.py setup \
  --mqtt-topic '/your-chosen-topic-string' \
  --traccar-email you@example.com \
  --traccar-password 'your-password' \
  --device-id your-device-id

Both values have to match the outdoor location engine’s prj.conf:

Flag	Firmware setting
`--device-id`	`CONFIG_DEVICE_ID`
`--mqtt-topic`	`CONFIG_MQTT_SN_PUBLISH_TOPIC`

MQTT-SN has no authentication, so pick a topic nobody can guess, such as [}xRDvRP:kN*:8.

Verify it end to end

Publishes a test position over MQTT-SN and reports which stage it reached, without needing a real device.


./findmycat.py verify \
  --mqtt-topic '/your-chosen-topic-string' \
  --device-id your-device-id

Stage	Meaning
`gateway`	The message reached the broker on the right topic
`rule sql`	Fields were extracted from the payload
`traccar`	Traccar accepted the position

Run this while the device is disconnected. MQTT-SN allows one live session per client id, so publishing as the device’s id would displace its session.

Succesful run looks like this:

Tearing it down

Stops the containers and removes the EMQX volumes, the Traccar database and its logs. It prints what it would remove and does nothing unless you pass --yes.


./findmycat.py destroy --yes

Using Docker

The following instructions are to help you setup the FindMyCat cloud software using docker entirely. Most of the setup has been automated and just involves running a couple start scripts. The only manual step is the Rule Engine configuration.

Pre-requisites

Regardless of what operating system you choose to host on, make sure the following are installed on it.

Clone Cloud repository

Clone the FindMyCat Cloud repository. Github: https://github.com/FindMyCat/cloud


git clone https://github.com/FindMyCat/cloud.git

Start Traccar Server

The docker-compose.traccar.yml file holds the configuration needed to initiate the Traccar server with a suitable traccar.xml, and it ensures the correct ports are open.


docker-compose -f docker-compose.traccar.yml up -d

A successful run would output something like this:


[+] Running 1/1
✔ Container traccar  Started

Start EMQX Broker

The docker-compose.emqx.yml file configures the EMQX Broker and enables the appropriate plugins for the Rule Engine and MQTT-SN gateway.

Start the EMQX Broker with:


docker-compose -f docker-compose.emqx.yml up -d

Observe a similar output for a successful run as the Traccar setup step.

Configure EMQX Rule Engine

Most of the setup for EMQX is already done in the previous step, the only thing to configure is the Rule Engine. The Rule engine is responsible for forwarding the incoming MQTT messages from the tracker device / homestation and relay them to Traccar server.

Follow these steps here to configure the EMQX Rule Engine. You can skip the “Enable MQTT-SN Gateway” step as it was already taken care by the docker file.

Manual Installation

The Manual installation instructions assume you are using Amazon Linux 2.

Setup EMQX MQTT Broker

Download EMQX v4.4.19


wget https://www.emqx.com/en/downloads/broker/4.4.19/emqx-4.4.19-otp24.3.4.2-1-amzn2-amd64.rpm

Install EMQX


sudo yum install emqx-4.4.19-otp24.3.4.2-1-amzn2-amd64.rpm -y

Start EMQX


sudo systemctl start emqx

You should see EMQX Dashboard UI on port 18083. (https://Your_AWS_Public_DNS:18083)

Setup Traccar GPS Server

Download Traccar server v5.8 and extract


wget https://github.com/traccar/traccar/releases/download/v5.8/traccar-linux-64-5.8.zip
unzip traccar-linux-64-5.8.zip

Execute traccar.run file


cd traccar-linux-64-5.8
sudo ./traccar.run

Start Traccar service


sudo systemctl start traccar

You should see the Traccar UI on port 8082 (https://Your_AWS_Public_DNS:8082)

Cloud providers

Any host with Docker works.

DigitalOcean

Setting	Value
Image	Ubuntu 24.04 LTS
Size	512 MB / 1 vCPU

Add 2 GB of swap. EMQX and Traccar do not both fit in 512 MB without it.


fallocate -l 2G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

Firewall:

Port	Access
`1885/udp`	Public. The tracker connects here.
`8082`, `18083`, `1883`, `5055`	Your IP only