Freematics + Traccar (integration and configuration)

freematics.md

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: 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): . 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
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.

Telegram invitation please: @aktech