Skip to content

Instantly share code, notes, and snippets.

@soshial
Last active October 22, 2024 13:59
Show Gist options
  • Save soshial/d07919e0fac67f5501a38fe3c39be416 to your computer and use it in GitHub Desktop.
Save soshial/d07919e0fac67f5501a38fe3c39be416 to your computer and use it in GitHub Desktop.
Freematics + Traccar (integration and configuration)

In this article I listed some common problems I encountered when I tried to use Freematics OBD-reader together with traccar device-tracking server. Both are open-source, thanks to which I was able to improve both and their cooperation.

Freematics: official repo and my fork.

traccar: official repo and my fork.

What are the pitfalls and hardware drawbacks of Freematics?

  1. Currently, Freematics cannot switch between WiFi and SIM depending on connectivity. If you want to switch to a different WiFi or mobile operator - you need to open your bloody Windows and recompile everything :)
  2. Doesn't work at all without external power, has no battery. Works only when connected to USB (3.7V), OBD-II (12V), or SAE J1939 (24V). It means that if a theif cuts off the device, Freematics would not be able to send the SOS signal to the server.
  3. ONE+ Model B (as well as Traccar edition) has an internal GPS receiver. Due to the antenna being in the enclosure, sometimes the location of the OBD port may prevent the antenna from getting a good GPS signal from the sky. You can use an external GPS receiver (costs around $10), but that is more suitable to be used with model A which has no internal GPS. Another approach is to use OBD port extender to put the tracker higher with access to sky.
  4. As far as I understood, there is no support for HTTPS: I don't think it is possible due to the size and complexity of the SSL Library, because the Arduino would most likely be underpowered. I tried using WiFiClientSecure library, but it didn't compile. Ways to circumvent it: A) make the requests to a regular server, that redirects/proxies it to the HTTPS server or B) use packet mirroring via WiFi router (any ideas how to do it?, does this work?).

How does Freematics internally work? (tracking logic of firmware_v5/telelogger.ino sketch)

PXL_20210711_091335589

  1. It has 2 types of requests, the first sends only events and alarms (without location) and the other sends only key-value data payload (location, ODB data, etc.).
  2. Device gathers data every X milliseconds (see the DATA_INTERVAL_TABLE parameter). The data gets immediately written to file storage as CSV files (but flushed incrementally with each 1 KiB, equal to approximately 6 records). Always choose SD card as a storage (#define STORAGE STORAGE_SD), since internal SPIFFS memory is very small and will cyclically rewrite itself.
  3. Freematics goes into standby mode after 180 seconds (the third value of STATIONARY_TIME_TABLE parameter). Wakes up after the accelerator sensor wakes it up. When in standby, Freematics pings the server every PING_BACK_INTERVAL seconds (15 min by default) and if there is no connection, then it just waits for the next 15 min.
  4. ✓ GPS, ✘ Internet. Freematics doesn't re-send any data collected while being offline, but only stores them on disk. NOT FIXED This approach has many flaws: if you had a ride in the area with bad network coverage, your route there will have significat gaps; or if you stopped your car in place A with internet, then moved to place B while being offline and then internet appeared in place B, then Freematics will send just ping events (not location data), and Traccar will show that your are still in place A. I will fix so that it will ping server and also transmit latest location. FIXED

What hardware to buy?

  1. OBD. If you have a car manufactured before 2000s, it probably will not support the OBD specification. I've also seen many complaints that Freematics has numerous problems with electric vehicles. In my case, Freematics DIDN'T work with my Renault's OBD-II port. I tested to figure out the perpetrator: an expensive OBD-reader from another manufacturer could read my ODB data, and Freematics was able to read other car's data. But eventually I realized, that OBD data is not that really needed for my purposes of tracking vehicle's location and movement. The main advantage of Freematics is that tha hardware comes with fully libre software, that you may customize as you wish. Do not expect that Stanley Huang (the creator of Freematics) will help you with your problems - you're on your own.
  2. External GNSS. I didn't want to buy the GNSS receiver from Freematics store (costs $40 + $17 delivery; €33 + €13 delivery) - it is definitely overpriced, so I bought one from AliExpress for €10 (+ €1 delivery). Same functionality, but 4 times cheaper. Be careful to choose GNSS receiver (and not just GNSS antenna). Make sure that it uses R-232 and NMEA-0183 protocol. Is has 4 colourful wires coming out of it. As of June 2021 I couldn't find dual-band GNSS with L1/L5 precision.
  3. SIM module. Choose SIM7600 module since it's the only one that supports 4G networks (along with 2g/3g). SIM7600E is for Europe and the whole world. SIM7600A if for US and Canada. On Freematics website SIM module costs $45 and you may buy an identical module for $35 on Aliexpress.
  4. Mobile data. Do not ever buy Hologram SIM (advertized all over Freematics website and even in the code). There are tons of different services that provide normal prices. I personally used MTX Connect SIM for 3 reasons: a flat fee of €0.012 per 1 MiB which is the same in all supported countries, very extensive list of countries (as of 2024): MTX coverage in 2024. Although there is one downside:

Also, please keep in mind that in our "Description of Services" says that you can' use our sim in same country more than 60 days continuously: "Permanent Roaming" means the use of Services within the same country for more than 60 (sixty) cumulative days within any 4 (four) consecutive months’ period

Problems with Freematics I encountered and fixed:

  1. ✘ GPS, ✓ Internet. In this case Traccar shows device status as online and green, but the location is actually outdated. Be careful and look at the location timestamp.
  2. Freematics should add checksum, according to its documentation as 2 characters (1 byte), but it doesn't start with leading zero when checksum is: 0 < checksum <= F. FIXED
  3. Originally, Freematics location and OBD data is saved to CSV files in a very weird format (completely different from format send via UDP or HTTP). This format prevents data to be easily re-uploaded later (if device was offline). I fixed it, so that it saves data in this format: M0ZR4X0#0:204391,11:140221,10:8445000,A:49.215920,B:18.737755,C:410,D:0,E:208,24:1252,20:0;0;0,82:47*B5. FIXED
  4. Freematics should send both temperature sensors' data (key 0x23: MEMS temperature and key 0x82: CPU temperature). Also, the values sent violate its own documentation (should send 12.3°C as integer 123). Also, as Stanley stated: CPU temperature is not from any type of thermometer. It is recommended to use MEMS motion sensor’s temperature data. FIXED
  5. Crossing national borders oftentimes renders Freematics offline (SIM card supports roaming). As a result: whole chunks of route do not get uploaded to traccar. NOT FIXED border problems 1 border problems 2
  6. Doesn't send cell tower data (called MCC, MNC, LAC, CID, RSSI). FIXED traccar Freematics
  7. Freematics' built-in internal GNSS receiver sent tons of zero locations (0, 0) for some unknown reason. Very often locations alternated each 2-3 seconds between accurate location and (0, 0). Thankfully, Traccar has filtering options <entry key='filter.zero'>true</entry> in configuration file default.xml.
  8. Freematics sometimes sends 2 streams of locations. NOT FIXED
  9. Freematics had had no support for sending ignition status (ON/OFF). FIXED Freematics and traccar. Sidenote, I had to lower the JUMPSTART_VOLTAGE threshold from default 14.0V to as low as 13.0V, since my car OBD port provides lower voltage.
  10. Low battery alarm was not sent. FIXED. Added LOW_BATTERY_VOLTAGE config parameter.
  11. NMEA receivers don't send location accuracy radius in meters (that we are accustomed to with using smartphones), but receivers send HDOP data (dilution of precision), which is not enough to calculate corresponding accuracy. The radius might be calculated based on receiver's HDOP accuracy and your desired degree of confidence, but it is not very reliable. I put Freematics under steering wheel, so it doesn't have access to clear sky, but the location accuracy is still quite good. Average HDOP I get is 70-100 which is considered bad, but comparing roads drewn on OSM and my drewn route the accuracy is ±2 meters. I guess we just have to relax about accuracy and try to put GNSS antenna with the best access to open sky. UNFIXABLE
  12. Overheating is determined by the temperature reported by the MEMS chip which reflect the device internal temperature. Try reducing data rate. This happens when cellular signal is weak and the cellular module increases its power consumption. Alternatively, this can be improved by having an external cellular antenna or sending data to server via WiFi.
  13. traccar main developer didn't foresee, that locations may arrive non-sequentially (sic!), for example when locations are re-uploaded. FIXED, needs to be configured to avoid data duplication.

How to pair Traccar with Freematics?

I used this reddit post as a foundation for my custom setup:

  1. I updated telelogger.ino to get the device to send over fuel level data by adding {PID_FUEL_LEVEL, 1}, on line 53. You can add other OBDs if you want, they're all defined in the OBD.h file.
  2. Change frequency of checking of GNSS location data; it is regulated by motion adaptive data interval control: STATIONARY_TIME_TABLE and DATA_INTERVAL_TABLE (setting and code)
  3. choose protocol #define SERVER_PORT 5170: UDP (5170 port, sends a lot of data including ODB) or HTTP/S (port 5055, sends only location data)
  4. add settings needed for device networking: either WiFi or SIM (looks like simultanious usage is not possible)

We have a group chat in Telegram. If you'd like to join, write down a comment and I'll send you the invitation link.

Please, send comment down below if I am wrong in some of my conclusions.

@soshial
Copy link
Author

soshial commented Mar 2, 2023

@ciroiriarte, please post here your nickname.

@roysbike
Copy link

roysbike commented Jun 19, 2023

@soshial please add telegram group. My nick @roysbike2

@arduino-man
Copy link

Is it possible to join the Telegram group still?

@soshial
Copy link
Author

soshial commented Aug 5, 2023

@arduino-man send me your telegram handle.

@arduino-man
Copy link

@air_compress Thanks

@sdntechforum
Copy link

Can someone please help me pinpoint where we have defined the server address as "demo.traccar.org"? I want to send data to my personal edition of Traccar server instead of the demo.

@fizzi
Copy link

fizzi commented Sep 6, 2023

Please add me to Telegram Group ... @francesco_izzi

@soshial
Copy link
Author

soshial commented Sep 6, 2023

Done, @fizzi

@machv
Copy link

machv commented Sep 8, 2023

could add me @u615119 too, please?

@apaperclip
Copy link

i'm in thanks!

@voklav
Copy link

voklav commented Sep 8, 2023

Another one, please
@voklav :)

@rknightion
Copy link

@nilzen I will try to rebase/merge my branch/repo with the master branch.

Thanks for all the hard work! - I'm curious on the Freematics fork you've got if it's possible to rebase from upstream? - I notice there's things like adding support via BLE, a sim7070 UDP fix and various other updates and I'm not sure which firmware would be "better" for a first starter?

@GuraXL
Copy link

GuraXL commented Nov 22, 2023

Hi, please add me on @yashodhag

@qnzkrew
Copy link

qnzkrew commented Dec 7, 2023

im having some issues as you guys have mentioned. im using hologram sim since they pushed me towards it but i can chnage .
i can connect it to my car eveything works great and after 15 minutes of driving the tracking stops and will not update even though it still says device online. it stays online and sometimes goes idle yet the last location is where it went offline and that doesnt move at all. i still see connection on hologram side also

@prestomation
Copy link

Please add me. My telegram and github user names are the same(prestomation@)

Copy link

ghost commented Jan 29, 2024

Please add me if possible, thank you. (@jm_ma_esp)

@Jetman80
Copy link

Hi!
Thanks for the useful article. FYI, I followed advice here and bought MTX SIM card. But it appeared:

  1. you cannot receive SMS without buying 60 euro per year additional package
  2. Quote their support:
Also, please keep in mind  that in our "Description of Services" says that you can' use our sim in same country more than 60 days continuously:
"Permanent Roaming" means the use of Services within the same country for more than 60 (sixty) cumulative days within any 4 (four) consecutive months’ period;

So MTX SIM cards are practically useless for GPS tracker purposes. I think it is worth sharing.

@soshial
Copy link
Author

soshial commented Feb 29, 2024

@Jetman80 wow, thank you!

  1. I never needed SMS and $60 is obviously overpriced, but their SIM is mainly for mobile data
  2. I didn't actually know that and haven't encountered this since I use primarily for travels. I'll add it to the manual

@pbvdven
Copy link

pbvdven commented May 4, 2024

Please send me telegram invite

@pbvdven

@ceeeru
Copy link

ceeeru commented May 8, 2024

Please add me to the telegram channel pls!
@CeruzaUR
I have some remart, maybe somebody can help me in that.
Sincerelly:
C.

@Cyberes
Copy link

Cyberes commented Jun 28, 2024

@soshial I implemented encryption to the UDP protocol sort of like how @rfhigler tried CHACHA. It uses a proxy server to decrypt the traffic and forward it to Traccar.

https://github.com/Cyberes/freematics-traccar-encrypted

@andreacappelletti97
Copy link

andreacappelletti97 commented Aug 5, 2024

Hello, I'd like to join the Telegram group. Thanks :)
@soshial

@AlejandroIbarraC
Copy link

Hi, just got a Freematics One+. Would love to join the Telegram group. @JAIbarraC

@alexandrepossebom
Copy link

Hi, I would like to join the Telegram group.

My username is @possebom

@msamancioglu
Copy link

telegram invitation please @msamancioglu

@aktech
Copy link

aktech commented Oct 17, 2024

Telegram invitation please: @aktech

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment