Freematics One+ Traccar in Home Assistant Set Up Troubleshooting

Inquiry and support for Freematics products
Post Reply
idaho7
Posts: 1
Joined: Tue Dec 07, 2021 7:18 am

Freematics One+ Traccar in Home Assistant Set Up Troubleshooting

Post by idaho7 »

I recently ordered three Freematics One+ units for use in my Taccar instance hosted *within* Home Assistant OS as a plug-in. Home Assistant OS is self-hosted by me, but most of the below will apply if you have one running on a VPS like Digital Ocean.

This is a very specific use case, and there were a bunch of weird gotchas as I was getting things set up, so I thought I'd list the issues and solutions for my setup here in the hopes that they help someone else down the line.

The general outline for this setup is:

* Install Visual Studio Code
* Install PlatformIO plugin for VS Code
* Download Freematics firmware source code
* Import firmware_v5/telelogger project
* Update config.h (see details below)
* Connect Freematics device via USB
* Click upload button to flash the firmware

Most steps have some ambiguity even though it looks straightforward. I'll go one by one.

* Install Visual Studio Code

This should be done on your local computer and not via the Studio Code Server plug in available in Home Assistant OS. The PlatformIO package has issues with installation on HA OS.

* Install PlatformIO plugin for VS Code

This is referring to the PlatformIO IDE. You can install it by opening Visual Studio Code (at least as of Version 1.62.3), clicking File > Preferences > Extensions and then searching the EXTENSIONS: MARKETPLACE for PlatformIO IDE.

* Download Freematics firmware source code

This one is straightforward. Just do what is says on the tin, and head to the github repo and download or clone the latest code.

* Import firmware_v5/telelogger project

After installing the PlatformIO extension in VS Code there is a little Ant looking icon in the left pane. Click on that and make sure the Home icon in the new PlatformIO panel is selected. There will be four big buttons: New Project, Import Arduino Project, Open Project and Project Examples.

Despite the directions to import, the choice the worked for me was to Open Project and navigate to the Freematics/firmware_v5/telelogger/ folder of the downloaded source code and click Open "telelogger".

* Update config.h (see details below)

Click on config.h in the sidebar and start editing. The details below list the configurations you will want to change. You'll need to change more or less, depending on the types of troubles you run into. Here are the configs I ended up customizing at some point, in bold, and what they do.
**************************************
* Networking configurations
**************************************/
#ifndef NET_DEVICE
// change the following line to change network device
#define NET_DEVICE NET_SIM7600 // NET_SIM7600 or NET_WIFI for testing
// WiFi settings
#define WIFI_SSID "Enter your Wifi SSID here"
#define WIFI_PASSWORD "Enter your Wifi password here"
// cellular network settings
#define CELL_APN "hologram"
// Freematics Hub server settings
#define SERVER_HOST "Enter your public IP address here. If self-hosting, be sure to forward port 5170 to the internal IP address of your Home Assistant OS."
#define SERVER_PROTOCOL PROTOCOL_UDP
#endif

#if !SERVER_PORT
#undef SERVER_PORT
#if SERVER_PROTOCOL == PROTOCOL_UDP
#define SERVER_PORT 5170 // The port Traccar listens for the Freematics One+ on
#elif SERVER_PROTOCOL == PROTOCOL_HTTP
#define SERVER_PORT 80
#elif SERVER_PROTOCOL == PROTOCOL_HTTPS
#define SERVER_PORT 443
#endif
#endif

/**************************************
* Data storage configurations
**************************************/
#ifndef STORAGE
// change the following line to change storage type
#define STORAGE STORAGE_SDSTORAGE_NONE // Since I do not have an SD card, I set this to STORAGE_SDSTORAGE_NONE.
#endif

/**************************************
* GPS
**************************************/
#ifndef GNSS
// change the following line to change GNSS setting
#define GNSS GNSS_EXTERNAL // Since I got devices with external antennas, I set this to GNSS_EXTERNAL
#endif
#define GPS_MOTION_TIMEOUT 180 /* seconds */
* Connect Freematics device via USB

VS Code will automatically detect the Freematics One+ when you insert it into the USB port. HOWEVER, if your port is not supplying enough power both the Wifi radio AND the Cell radio will fail. Be sure to plug the device into a USB port with full power! I plugged mine into a hub at first and it connected and I thought all was well. But just because you can upload code to the device DOES NOT mean the radios will function correctly. I can't underline this enough.

* Click upload button to flash the firmware

You actually want to click the Ant icon again after you've finished editing config.h, and then click Upload and Monitor in the left Project Tasks pane. Monitoring is absolutely crucial, as it shows the serial output from the device. It's the only way you'll know what is working and what is not.

If you get an error like:

Code: Select all

serial.serialutil.SerialException: [Errno 13] could not open port /dev/ttyUSB0: [Errno 13] Permission denied: '/dev/ttyUSB0'
*** [upload] Error 1
and are using Linux like me, you need to chmod (change mode) the USB device. For me this meant I needed to open a terminal and type:

Code: Select all

sudo chmod a+rw /dev/ttyUSB0
You'll probably run into 2-3 showstoppers almost immediately, unless you got everything perfectly configured on the first try. The things I ran into:

1. No Wifi. - First, to use wifi for testing I needed to change the #define NET_DEVICE NET_SIM7600 line to #define NET_DEVICE NET_WIFI. Next I needed to plug the Freematics One+ into a powered port at the back of my PC instead of the keyboard hub.

2. No CELL. - This was two things all at once. 1) I had the device plugged into an under-powered USB hub. And 2) where my desk is located in not well covered by Hologram, the IoT cell provider I am assuming you are also using since it comes supported out of the box. This means I had to use Wifi for testing that the device could actually connect to my self-hosted Home Assistant instance. I was also confused where to put the cell SIM card. it goes in the slot nearest the side of the Freematics One+ with the white logo and icons, and the gold chip needs to face up toward that logo side of the device, and the little notched end of the SIM card should be on your left as you insert it. (The bottom slot is for SD cards.)

3. No location coordinates in the serial output. - This was because the antenna really needs direct line of sight with the sky. I solved this by taking the unit to an area where I could position the external antenna by a window and powered it on with what I believed were known good credentials and ports.

4. However it still didn't communicate with Traccar. This was because there is an XML file in the Home Assistant OS config directory (the same location as your HA configuration.yaml file) called traccar.xml that has a line

Code: Select all

<entry key='freematics.port'>5170</entry>
that must be uncommented for Traccar to open the port Freematics One+ uses to communicate.

5. Don't forget to add the device id to Traccar itself! The ID is printed on the device itself. If you click the + button in the Traccar UI it will bring up a Device modal. Two fields are required: Name and Identifier. The device ID goes in the Identifier field.

After everything was configured correctly, I was able to get my device to show up using wifi. Then I switched back to NET_SIM7600, recomplied and uploaded, installed in my vehicle and took a long drive. When the cell radio finally got into an area that had good coverage, everything just started working. It took a while, and there was much despair for many minutes. So hopefully your config is known good and you can just be patient.

Hope this helps someone!
Post Reply