Freematics ONE+ is based on ESP32 and can be programmed as Arduino. We provide Arduino library and reference code for the hardware on which developers can evolve their own products with least efforts. If you are a pro, we highly recommend to use PlatformIO IDE as the development environment, though Arduino IDE or Arduino Makefile with ESP-IDF can be used as well. For beginners, we provide a dedicated tool for configuring, compiling and uploading the code for a quick start.
First of all, let’s get to know about the physical interfaces Freematics ONE+ has.
- OBD-II Male Connector (16-pin)
- GPIO Socket (4-pin)
- microSD card slot
- Micro SIM card slot (not used for units without cellular module)
- Micro USB Port
- xBee Socket (inside)
- LED Indicator
OBD-II Male Connector
OBD-II male connector allows Freematics ONE to be plugged directly into OBD-II female port which is available in most modern cars. The OBD-II port provides connection between Freematics ONE and car’s ECU computer as well as power supply from car battery.
Freematics ONE+ has an external I/O socket on its enclosure. The 4-pin socket contains of 2x GPIO (from ESP32), VCC and GND. A 2.54 Molex connector is used for wiring. The line definition of the connector is as following.
- GPIO32 / Rx2 (ESP32)
- VCC (5V)
- GPIO33 / Tx2 (ESP32)
This socket allows connection of external GPS receivers which come as an optional accessory. The 4-pin connector is used for serial communication and also providing power for GPS receiver. Normally OBD-II port sits underneath dashboard where no good GPS signal reception is available. External GPS receiver with a cable led out from Freematics ONE can be easily placed on dashboard or somewhere else for better signal reception.
Freematics ONE has a microSD card slot and a micro SIM card slot under the plastic cover on one side of the enclosure. Both card seats are self-popping. Please avoid insert anything into SIM card slot if your Freematics ONE has no cellular module installed. Please make sure to insert microSD card and SIM card in the correct direction as shown below.
Micro USB Port
Micro USB port is used for Arduino sketch uploading as well as serial communication which is pretty same as for an Arduino board. The port can also be used for powering the device if no OBD-II connection is available.
LED indicator are on when powered on and flashing when there is USB or BLE communication.
A 2x10pin xBee Socket is set on the PCB. It allows extension for wireless communications like cellular network connectivity or xBee communication.
All the peripherals are hooked to the main controller ESP32 as following.
|OBD-II (STM32)||SPI: GPIO18(SCK),GPIO19(MISO),GPIO23(MOSI)
STM32 CS: GPIO2, STM32 READY: GPIO13
|GPS||UART2: GPIO32(RX) GPIO33(TX)
Power control: GPIO15
|Cellular Module (xBee)||UART1: GPIO16(RX) GPIO17(TX)
Module power switch: GPIO27
SD CS: GPIO18
|USB Serial||UART0: GPIO3(RX) GPIO1(TX)|
Normally there is no need to concern about the pin mapping as the details are encapsulated in the Arduino library.
Compiling and Uploading
Freematics ONE+ uses ESP32 as main controller. ESP32 has an actively developing Arduino core which makes it programmable as Arduino. Most important Arduino libraries like SPI, Wire and WiFi are well ported. There are a couple of ways to compile Arduino sketch for ESP32 and upload to it. Arduino IDE might be the most popular choice (setup guide here), however emerging modern IDEs are outperforming it in all aspects especially with better support for new Arduino variants.
We have developed a fully functional Arduino sketch named Telelogger, as the reference code for Freematics ONE+. It sets up peripherals and network, collects data from multiple sources and transmits the data to Freematics Hub (telematics server software), via WIFI or cellular network. Currently UDP is used as transport protocol. With available source code, it is not difficult to alter the transmission to work with your server. The sketch and library for Freematics ONE+ are hosted on Github. Get a copy of the code by Github desktop software, command-line git, or simply downloading a ZIP tarball of the repository.
The sketch is configured by a config.h file. You normally need to change something there at the first time to reflect your settings, like WIFI SSID/password (when WIFI used for networking) or your cellular operator’s APN (when cellular network used). You can also turn on/off some features like GPS or 9-DOF sensor from there.
The code of Telelogger is organized as a PlatformIO IDE project, so it is very straight-forward to use the IDE to get the work done. First you need to install PlatformIO IDE by visiting the official website and following the very concise guide. PlatformIO IDE is built on top of two popular code editors, Github’s Atom and Microsoft’s Visual Studio Code. You can choose one according to your preference. The screenshots following are from Atom version.
Once the IDE is installed, load the folder of Telelogger (which contains file platformio.ini) and the project is ready for developing and compiling. The first loading may take a while as the ESP32 package is downloaded and installed on demand.
While waiting for the IDE to get ready, use USB cable to connect Freematics ONE+ to your computer’s USB port. PlatformIO will automatically detect serial port and normally you don’t need to alter it to start uploading. Simply press F7 (or click the Upload button on left sidebar) and choose Upload from the popup menu. It will go like the following.
PlatformIO has built-in serial monitor. Once the uploading is done, and if Freematics ONE+ is in your car’s OBD-II port or you have a Freematics OBD-II Emulator which can be more convenient, you can open the serial terminal to monitor the working status from the serial output right away.
You can also monitor status output wirelessly with a BLE terminal app (e.g. LightBlue on iOS or BleTerm on Android).
Freematics Arduino Builder
We have been maintaining a self-contained utility for compiling and uploading Arduino sketch. Whether you have or haven’t heard about it, it’s named Freematics Arduino Builder. You will download a 7z package containing an executable file and everything needed for accomplish the task. Simply extract the package and run the executable. The utility is especially convenient when no developing is taking place and is actually more productive for uploading for a batch of devices.
We have recently implemented a user friendly XML file driven configuration GUI for Arduino sketches we have developed. As you might have noticed, there is a config.xml in the folder of Telelogger sketch. This file contains selectable options and will be rendered into a configuration GUI when the sketch is loaded from Freematics Arduino Builder like the following.
Some extra compiler options are automatically generated according to the change in the GUI and the options will be applied to compiling the same way config.h does (and override it).
After making changes to the configuration GUI, you can complete the compiling and uploading with just one click on the serial port button (you will still need to make out which serial port corresponds to Freematics ONE+).
When compiling and uploading are completed, click Open button to open the serial monitor to watch the results of running sketch. You can also tick “Auto Open Port” so that the serial monitor is automatically opened after uploading.