Kid Tracker

Motivation

The project includes both server side and web application designed to communicate with kids smartwatch devices equipped with GPS tracker of different models and known under various brands. For example, it can work with Q50, Q60, Q80, Q90, Q100, Q360, Q523, Q730, Q750, Q8, GW100, GW100S, GW200, GW200S, GW300, GW300S, GW400S, GW400X, GW500S, GW600S, GW700, GW800, GW900, GW900S, GW1000, GW1000S, EW100, EW100S, EW200, K911, W8, W9, W10, Y3, G36 SAFE KEEPER, DS18, T58, T100, I8, G10, G100, D99, D100, D100S, and many others. Roughly speaking, it does the same as such applications as SeTracker, FindMyKids, and so on. The main difference is that all personal data, like contacts, positions, communication history, and so on, becomes truly private, since it is stored on hardware controlled by user.

Another issue which was addressed is the security model of kids smartwatch communication and tracking applications. By default, any person could take control over the device provided the device identifier is known, with no further confirmation of being a device owner. The identifier, in its turn, can be easily obtained by sending a text message to the device if the device cellphone number is known. There is a password, of course, but all devices have the very same factory password and there is no annoying notifications asking to change it, therefore no one does that.

In this application the following security scenarios have been implemented:

Device assignment is protected by two-factor authentication: both the device identifier, and a four-digit token sent to the device are required to assign the device to a user.
There is a set of "protected" operations, such as turn the device off, reset to factory settings, unassign the device, and settings the device password, which are protected by token sent in a text message to user cellphone.
Users are not allowed to modify their cellphone number once it is set on creation time to protect devices from unwilling commands even if user account is compromised.
Any user having access to a device can list all other user having access to this device.

And last, but not least, it is free of charge and ads :).

Getting started

Build application

Building the project is as simple as

docker compose -f docker-builder.yml run --rm builder

While building, an SSL certificate required for https connections is created. It is possible to specify a domain and/or an ip address using environment variables DOMAIN and IP

docker compose -f docker-builder.yml run --rm -e DOMAIN=example.com -e IP=123.45.67.89 builder

Choose the database and start the application

The application can be backed by different databases, on your choice. The most lightweight scenario is to use embedded H2 database. In this case application can be started with command

docker compose --profile h2 up -d

It is also possible to use PostreSQL, either containerized, or standalone. In the former case you can start application with command

docker compose --profile pg up -d

In the latter case you have to complete file db.env with database URL and credentials and then run the command

docker compose --profile pg_ext up -d

If your version of compose doesn't support profiles, you can use dedicated compose files for each scenario

docker compose -f h2.yml up -d
docker compose -f pg.yml up -d
docker compose -f pg_ext.yml up -d

In the last case you still need to complete db.env file with database URL and credentials.

Run from binary

It is also possible to skip the boring building phase and run the binary attached to release (java 8 or higher is supposed to be installed)

java -jar kidtracker.jar

The binary is configured to use embedded H2 database. Three folders are created on frist startup in the working directory:

data contains database records for device locations, phone numbers, etc, this date is confidential, so keep it safe!
logs self-descriptive enough, contains logs, both for the application itself, and for devices when device debugging is active,
media this folder is used to convert incoming audio in amr format into mp3

Logging in

Web UI is available on https://<hostname>:8003. To log in, use default credentials admin/password.

Assign a device

To assign a device to a user registered to the application, the application should be available from public networks, that is, it should have a public ip address, and, probably, an associated domain name. By default, the application listens devices on port 8001, suppose the very same port is mapped to the public network. Then the following text message sent to the device makes it start connecting to the application:

pw,123456,ip,<public IP address or domain>,8001#

Here 123456 is the default password, which is most probably set on the device. Other known default passwords are 523681, 54321, and 654321. If, however, the password was changed, the new password should be used instead of the default one.

It is highly recommended changing the default password!

Then click button on the right-hand side of the navigation bar and then click button on the footer. The device identifier is required for device to be assigned. Once the device is connected to the application, four-digit confirmation token is sent to the device. To confirm user owns the device, this token should be entered to the pop-up form during next 5 minutes, after that time token expires.

Usage notices

User roles

Any user registered to the application can either be a regular user, or an administrator. Administrators can register other users, whereas regular users cannot, this is the only difference. Administrators can create both regular users and other administrators. For existing user, administrator privilege can be neither granted nor revoked, the only way to modify it is to remove user account, and recreated it anew.

For security reason, the user cellphone number cannot be modified neither. Again, to change it the user account is to be removed and recreate. To remove user account, all devices have to be unassigned from it.

When run for the very first time, there is a default user account with administrator privilege with login admin and password password. It is recommended either removing this account when other user accounts are created, or changing the default password. If there is only one account with administrator privilege, it cannot be removed. The default administrator account has no valid cellphone number, and no device can be assigned to it.

Communication with device

Devices communicate to the application by means of messages. There are several types of messages, some can provide information about the device location and alerts, others contain actual battery charge and pedometer value.

Some messages can also be sent by the application to a device to make it perform several actions or modify its settings. To assure the device has received the message, it sends a confirmation message back to the application. While waiting the confirmation message, the UI remains blocked. If no confirmation is received in 10 seconds (can be configured), the initial message is considered to be not confirmed.

User interface

Device markers

Position markers of all assigned devices together with user position marker share the same map. Device markers contain information about time of last known location, battery charge, pedometer value, and eventually the device take off alert , low battery alert , connection lost alert , and obsolete location alert . The device is considered to be lost if the last message from the device was received more than 15 minutes ago.

Device could provide its actual location, based on direct GPS data, when it is available, as well as last detected position, when direct GPS observation is not available, mostly inside buildings or in the presence of electromagnetic noise, in such cases the GPS data
is considered obsolete. When received location data is obsolete, the obsolete data alert is shown.

Notice that the low battery alert , and actual charge value come in different types of messages. Messages with actual charge come more frequently (each 5 minutes) than messages with locations and alerts, which can be not sent for hours. Therefore, it is not uncommon for a marker to show 100% of battery charge together with low battery alert. In this case the priority is for numerical value of the battery charge and low battery alert can be ignored.

Device sends alarm messages when the SOS button is pressed. The device marker becomes red in this case, and a siren sound is played until the marker is clicked. Marker clicking results moving it on top and switching kid select. When kid select is switched, the selected device marker goes on top.

Device can send audio messages and (if equipped with camera) snapshots to the application. When new message of this kind arrives, the device marker becomes blue, and the vintage phone ring sound is played until the marker is clicked. As in the alarm case, marker clicking results moving it on top and switching kid select.

Timestamps

Anywhere in UI timestamps are clickable, and by a click can be switched between absolute date and time value and time interval from now.

Map view

There are two icons which have two states, filled and wired. First one becomes filled when map view follows selected device marker. Its state can be toggle by clicking on it. Another one becomes filled when map view follows user position marker. Its state can also be toggled by clicking on it. When one icon becomes filled another becomes wired and vice-versa. Both icons become wired when map is dragged.

Wake up GPS

By clicking on a command to wake up GPS and provide the current position is sent to the device. The map view starts follow the device marker, the follow device icon becomes filled.

Chat dialog

Chat with device is asymmetric. Text chat messages can be sent to device with button , whereas the device can send short audio messages and, if device is equipped with camera, snapshots. Device can also be forced to take a snapshot with button or make a 15 seconds audio record with button .

History dialog

History dialog allows choosing time interval in two modes, the date, from one midnight to the next one, and general, where both the start, and the end of the interval can be picked by user. To switch between modes click on date and time picker labels.

When time interval is picked, the chat history , or pedometer and battery charge graph can be shown. The device track for picked time interval can be put on the map as well. A slider appears at the right top corner, it is used to move device marker along the track. When history track is inspected, the history dialog icon is changed to . To remove the track and get back to online marker positions, click on it.

Contacts dialog

Contacts dialog allows editing primary and secondary device administrator , SOS numbers , device contacts , numbers allowed to make calls to the device , and quick call numbers assigned to device buttons. For all contact categories there is a fixed number of slots which can be filled. By default, empty slots are hidden, but can be shown by clicking on button at the dialog footer.

Kids dialog

Kids dialog allows user to assign and unassign kid devices, change thumb, and obtain some general information about the device and its actual status. In the left-hand side column a clickable thumb is placed, clicking on it results the kid edit dialog. In the middle column there is the device identifier. If the device is online, its identifier is in green, otherwise it is in red. Below the device identifier there is the time when last message was received from the device. All users having access to the device are listed at the rightmost column with their cellphones.

sumpurns/kidtracker