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.
* Connect Freematics device via USB**************************************
* 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 */
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 1Code: Select all
sudo chmod a+rw /dev/ttyUSB01. 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>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!