tobadia / petgps

A DIY, python-based framework to set up a server and exchange TCP packets with a chinese GPS+SIM (2G) device whose communication protocol is derived from something called GT06

PetGPS

This is a DIY-project to equip my cat (and hopefully, yours) with a small GPS tracker that is fitted with a SIM card to enable real-time location. There are many commercial alternatives to such a project, but they basically all rely on:

• 2G chipset with nanoSIM slot
• GPS chipset
• Sometimes, WiFi chipset capable of listening to nearby SSIDs (for location-based algorithms)

These commercial alternatives are absolutely overpriced (device 80 EUR as of today + usually charging a montly service fee, ranging from 3 to 8 EUR). In fact, the design is based on cheap knockoff IoT devices available from a well-known chinese wholesale website. The amount of data used by this kind of tracker is minimal (like, REALLY small, maybe up to 1 or 2 Mb per day of use), and as such, there must be cheaper alternatives to these commercial things... M'kaaaay ?

On the other hand, the chinese alternatives are provided with ugly UI for their ad-hoc services... and I don't want anyone in China to know where my cat goes out!

This repo hosts some developments I have made while using these devices called ZX612 and ZX303 from AliExpress. As of now, it is a complete WIP project, and the code is ugly, but hopefully decently documented. The ultimate goal is to have:

1. A stand-alone Python server that communicates with the device
2. A web UI that reads location logs from the server and shows where my cat has been and when.

Link for purchasing these devices: ZX612 and ZX303 (The ZX303 has more feature for the same size and I'd go with that one). If you want a battery included, order the versions with small plastic casing.

Protocol documentation

The protocol documentation for these devices is extremely poorly written. It was sent to me by the seller in the form of a Word document, available in the resources folder. It seems to be derived from the GT06 protocol, also documented in the same directory. I have somewhat re-written the documentation into an Excel document where each column represents a byte, for each kind of packet sent or received by the device.

Basically:

1. Device starts and sends a 'hello' packet to the server
2. Server acknowledges the device
3. Device send location-based data (either direct GPS coordinates or proxy informations)
4. Server send proxy informations to a location API; GPS coordinates are acknowledged
5. Repeat

These devices can be controlled by sending them SMS or data packets in the form of hexadecimal strings. The general format is 7878 XX YY ZZZZ 0D0A

• 7878: (2 bytes) start bytes
• XX: (1 byte) Data length. For some protocol numbers (see YY this is not the length but a parameter, e.g. number of SSIDs for WiFi location-based data)
• YY: (1 byte) Protocol number (defining what the data will be)
• ZZZZ: (varying length) Long chain of hex data that will be interpreted according to the value of YY
• 0D0A: (2 bytes) Stop bytes

Google Maps API key with dotenv

Your Google Maps API key is strictly private. It should NEVER be shared with anyone, as it enables querying the API without further login. An API key made public exposes you to unauthorized use, breach of Google's API Terms of Services, or massive querying possibly rsulting in you having to pay the bill once free queries have been exhausted. You don't want that to happen, do you ?

The dotenv Python library is used to import the content of a .env file into the environment upon starting the main script. This is convenient to set your private API key in a file that will not make it into the Git repository. An empty exemple of this file is available here in the Git repository. The .gitignore file from this repository is set to not track the real .env file. As such, you should add your API key in a local copy of .env derived from the example file, e.g. with:

cp .env.example .env
vi .env

Remember to not remove .env from the .gitignore file !

Running the server

Port forwarding

The server is set to run on port TCP 5023. Remember to redirect that port towards the machine that will run the server.

Start

After you've created the actual .env file, you're all set. Just run:

python gps_tcp_server.py

Data should now be coming in.

Stop

Ctrl+C twice will kill the current connection and then kill the server.

Some more README

...to be written here

petgps's Issues

Documentation or Manual

Hi

Congratulation for your work. Could you to do a manual or documentation to implement yor develop. I purchase the ZX303 model but I'm not can implement your PETGPS work.

Thanks

Reverse Engeneering

Hey, nice Project! These little Trackers are awesome in size and function. The only thing I hate is the hardcoded stuff like the default server for fallback. Anybody who ever tried reverse engeneering these little pcbs? extracting firmware, flashing firmware, modify the firmware, remove the hard coded Server IP, add or modify commands?
Ive searched the whole internet, but seems like nobody ever did this step.

Reading packet with recv

Hi. I see that you read a packet without any loops with one recv. But afaik it can returns partial data.

I could be wrong, didn’t jump deep into the code.

Gps functions

Hey! can you help me with few questions about this device?:

1. With this cheap modules do you have to interact with the button? Or they start powered "on"?
2. Do they support 3G?
3. that 1-2 MB daily data you said was using what rate? Does the device automatically saves data when there is no movement?

Thanks!

error when I receive the connections

Hi
Thanks for sharing with the community your work.
I have cloned your repo, and I have created a key for maps API.

But when I receive an incoming connection I receive this error:

127.0.0.1:41748 has connected.
[ 127.0.0.1 ] IN Hex : 474554202f20485454502f312e310d0a486f73743a206c6f63616c686f73743a393939390d0a557365722d4167656e743a204d6f7a696c6c612f352e3020285831313b205562756e74753b204c696e757820693638363b2072763a32342e3029204765636b6f2f32303130303130312046697265666f782f32342e300d0a4163636570743a206170706c69636174696f6e2f786d6c2c6170706c69636174696f6e2f7868746d6c2b786d6c2c746578742f68746d6c3b713d302e392c746578742f706c61696e3b713d302e382c696d6167652f706e672c2a2f2a3b713d302e350d0a4163636570742d456e636f64696e673a206964656e746974790d0a582d466f727761726465642d466f723a2038322e38342e31312e3137370d0a582d466f727761726465642d486f73743a207265706f72742e70726f67726573736966792e69740d0a582d466f727761726465642d5365727665723a207265706f72742e70726f67726573736966792e69740d0a436f6e6e656374696f6e3a204b6565702d416c6976650d0a0d0a (length in bytes = 394 )
[ 127.0.0.1 ] ERROR: socket was closed due to the following exception:
'20'
This thread is now closed.

What is 20 exception?

EDIT:
I have printed the stack trace:

Traceback (most recent call last):
  File "/home/progressify/Documenti/dev/petGPS/gps_tcp_server.py", line 93, in handle_client
    keepAlive = read_incoming_packet(client, packet)
  File "/home/progressify/Documenti/dev/petGPS/gps_tcp_server.py", line 131, in read_incoming_packet
    protocol_name = protocol_dict['protocol'][packet_list[1]]
KeyError: '20'

Protocol dumps

Hi, do you have some examples of device communication data? If yes, could you please share them?

Audio in zx620

Congratulations on your work, I am trying to configure a topin zx620 gps, and petGPS works perfectly, but this device allows you to send audio to the server and I can't get the server to receive it, do you know anything about this? Thanks

Old position reported

Hello,

I'm just starting using this python script and facing a strange issue for me, which maybe is normal I don't know.

Before switching to the script, GPS365 report a wifi position on 04 August which is good :

then switched to my computer, and it report a position from 27 July which was a good position this day but outdated :

pi@ragnar:~ $ tail logs/location_log.txt -f
2021/08/04 17:41:00 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.4064013 +2.7940479 116.1
2021/08/04 17:43:01 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175
2021/08/04 17:45:01 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175
2021/08/04 17:47:07 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175
2021/08/04 17:49:02 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175
2021/08/04 17:51:03 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175
2021/08/04 17:53:04 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175
2021/08/04 17:55:04 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175
2021/08/04 17:57:14 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175
2021/08/04 17:58:35 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175
2021/08/04 18:00:36 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175
2021/08/04 18:02:36 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175
2021/08/04 18:04:42 10.0.0.2 359339075435809 LBS-GSM-WIFI 2021/07/28 21:34:51 1 +48.407402100000006 +2.7956312 1175

here is an example of received frames :

[ 10.0.0.2 ] IN Hex : 78780713374c0819390d0a (length in bytes = 11 )
The current packet is for protocol: status which has method:
[ 10.0.0.2 ] STATUS : Battery = 55 ; Sw v. = 76 ; Status upload interval = 8 ; Signal strength = 25
[ 10.0.0.2 ] IN Hex : 78780517210728193451caeac75f117c4fcaeac75f117e4fcaeac75f117d5118d6c7902df45b1ad6c7902df45c0200d01455fc1d985a55fc1d9664000d0a (length in bytes = 62 )
The current packet is for protocol: wifi_offline_positioning which has method: datetime_position_response
[ 10.0.0.2 ] POSITION/WIFI : BSSID = ca:ea:c7:5f:11:7c ; RSSI = -79
[ 10.0.0.2 ] POSITION/WIFI : BSSID = ca:ea:c7:5f:11:7e ; RSSI = -79
[ 10.0.0.2 ] POSITION/WIFI : BSSID = ca:ea:c7:5f:11:7d ; RSSI = -81
[ 10.0.0.2 ] POSITION/WIFI : BSSID = 18:d6:c7:90:2d:f4 ; RSSI = -91
[ 10.0.0.2 ] POSITION/WIFI : BSSID = 1a:d6:c7:90:2d:f4 ; RSSI = -92
[ 10.0.0.2 ] POSITION/LBS : LAC = 22012 ; CellID = 7576 ; MCISS = -90
[ 10.0.0.2 ] POSITION/LBS : LAC = 22012 ; CellID = 7574 ; MCISS = -100
[ 10.0.0.2 ] OUT Hex : 787807172107282134510D0A (length in bytes = 12 )
Decoding location-based data using Google Maps Geolocation API...
Google Maps Geolocation API queried with: {'wifi': [{'macAddress': 'ca:ea:c7:5f:11:7c', 'signalStrength': -79}, {'macAddress': 'ca:ea:c7:5f:11:7e', 'signalStrength': -79}, {'macAddress': 'ca:ea:c7:5f:11:7d', 'signalStrength': -81}, {'macAddress': '18:d6:c7:90:2d:f4', 'signalStrength': -91}, {'macAddress': '1a:d6:c7:90:2d:f4', 'signalStrength': -92}], 'gsm-cells': [{'locationAreaCode': 22012, 'cellId': 7576, 'signalStrength': -90}, {'locationAreaCode': 22012, 'cellId': 7574, 'signalStrength': -100}], 'gsm-carrier': {'n_gsm_cells': 2, 'MCC': 208, 'MNC': 20}, 'gps': {}}
Google Maps Geolocation API returned: {'location': {'lat': 48.407402100000006, 'lng': 2.7956312}, 'accuracy': 1175}
[ 10.0.0.2 ] OUT Hex : 787815172b34382e3430373430322C2b322e3739353633310D0A (length in bytes = 26 )

so I don't know why this is an old one ? note there is no gps location for now.

board is ZX303, pet is a Beagle Dog but we don't care :)

thanks.

License

Hey,
I'd really like to fork this, but I would love if you could add license to your repository, so it is clear what your conditions for reusing this code are.

Problem with googlemaps API

First of all, thank you very much for your project, it is quite interesting how you decrypted the data sent to the server.

Of course, I have a problem regarding the googlemaps API.
I am running this script on a raspberry, even though I had some misconceptions regarding phyton to run the script and in addition to getting an API from google, I was finally able to start the server.

The problem is that the script, at the moment of giving the coordinates, indicates an error that does not appear:

Decoding location-based data using Google Maps Geolocation API ...
Google Maps Geolocation API queried with: {'wifi': [{'macAddress':' e4: ab: 89: 59: 68: 30 ',' signalStrength ': -28}, {' macAddress': 'e4: ab: 89: 59: 68: 00 ',' signalStrength ': -28}, {' macAddress ':' c6: d4: a1: 90: 23: ef ',' signalStrength ': -38}, {' macAddress ':' b0: b2: 8f: 42: ba: 3b ',' signalStrength ': -54}, {' macAddress ':' b0: b2: 8f: 42: b1: 2b ',' signalStrength ': -54}, {' macAddress ':' b2: 68: e6: 62: 95: 4f ',' signalStrength ': -57}, {' macAddress ': '60: 08: 10: 0f: 1b: d4', 'signalStrength': -60 }, {'macAddress': 'c0: 25: e9: 64: 2e: 2c', 'signalStrength': -73}], 'gsm-cells': [{'locationAreaCode': 29721, 'cellId': 9038, 'signalStrength': -90}, {'locationAreaCode': 29721, 'cellId': 8456, 'signalStrength': -100}, {'locationAreaCode': 29721, 'cellId': 21511, 'signalStrength': -100}, {'locationAreaCode': 29721, 'cellId': 8454, 'signalStrength': -100}], 'gsm-carrier': {'n_gsm_cells': 4,' MCC ': 730,' MNC ': 2},' gps ': {}}
[191.125.49.87] ERROR: socket was closed due to the following exception:

This thread is now closed

Do you ahve any idea how to solve that? or is it is okay?

HomeAssistant integration

Bought myself too a CAT gps Tracker, its indeed also based on 365GPS (topin)
http://www.topin.hk/web/

is there also an integration possible for Home Assistant?

thnx in advance