Skip to content

Instantly share code, notes, and snippets.

Last active Sep 12, 2021
What would you like to do?
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)


  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: the flat fee of €0.01 per 1 MiB which is the in all supported countries, very extensive list of countries and free traffic for messengers (Telegram etc.)

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. IMAGE NOT FIXED
  6. Doesn't send RSSI data. FIXED. Doesn't send cell tower data (called MCC, MNC, LAC and CID). NOT FIXED
  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=''>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, the default JUMPSTART_VOLTAGE being 14V was too high threshold for my vehicle, since my car voltage when driving varied between 13.4-14.4V, sometimes as low as 13.0V.then I put threshold to 13V and it worked perfectly.
  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.

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)

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

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