3 Connect Vehicles to Oracle IoT Fleet Monitoring Cloud Service

A device connected to the vehicle sends real time data to Oracle Internet of Things Cloud Service. A data logger connected to the OBD-II port of a fleet vehicle is a common device used to transmit location and operational data to Oracle Internet of Things Cloud Service. A device model defines what data is collected and forwarded to Oracle IoT Fleet Monitoring Cloud Service. Oracle provides a default device model to collect typical OBD-II data.

Vehicles cannot transmit location and operational data independently. A data logger must be installed to allow vehicle data to be transmitted to the cloud service. A data logger is a physical device that is connected to the OBD-II port of a vehicle. The data logger reads the OBD-II data and then transmits the data to the cloud service.

Device Models Overview

A device model is an interface that lets any device communicate with Oracle Internet of Things Cloud Service regardless of its manufacturer or operating system. A device model can represent a device, gateway, device adapter, or a device application.

A device model provides Oracle Internet of Things Cloud Service access to:

  • metadata associated with the device type

  • message formats generated by the device

  • exposed web resources that can be used for sending commands

  • device capabilities, such as device software management

A device model is uniquely defined by a Uniform Resource Name (URN). For example:
{
   "urn": "urn:com:mycompany:mydevices:driverdevice1",
   "name": "Driver Device 1",
   "description": "A device assigned to driver 1",
   "system": false,
   "attributes": [ ],
   "actions": [ ],
   "formats": [ ],
   "links": [ ]
}
A device model uses the URN as its unique identifier (ID). It also has a descriptive name and an optional description. When the system attribute has a value of true, it indicates that the device model was provided with Oracle Internet of Things Cloud Service instance. Each device model can be enhanced with three additional lists: attributes, actions, and message formats.

A device model’s attributes represent the variables that the device supports. Here is an example:

   "attributes": [ 
      { "name": "oxygenSaturation", "type": "NUMBER" },
      { "name": "heartRate", "type": "NUMBER" }
   ]

Each attribute has a message format and web resources associated with it. Some device models are defined only by their attributes, but most are defined by some combination of attributes and accompanying alert message formats. Attributes may be read-only or readable and writable.

The actions identify the methods that can be remotely invoked on the device. They are similar to attributes, but are in invocable state, instead of readable state. Here is an example:

   "actions": [
      { "name": "initialize", "description": "Returns the temp in C", "argType": "NUMBER" },
      { "name": "reset", "description": "Min measured value since ON" }
   ]

Formats specify the types of messages that the device can send to Oracle Internet of Things Cloud Service. The URN defined is the ID used and must be unique. Here are two examples:

   "formats": [
      {
         "urn": urn:oracle:iot:device:pulseoximeter",
         "name": "Pulse Oximeter Data"
         "description": "Pulse Oximeter format",
         "type": "DATA",
         "value": {
            "fields": [
                { "name": "oxygenSaturation", "type": "NUMBER", "optional": false },
                { "name": "heartRate", "type": "NUMBER", "optional": false }
            ]
         },
         "links": [ "..."]
      },
      {
         "urn": urn:oracle:iot:device:pulseoximeter:fatal",
         "name": "Pulse Oximeter Alert"
         "description": "Fatal alert for pulse oximeter",
         "type": "ALERT",
         "value": {
            "fields": [
                { "name": "oxygenSaturation", "type": "NUMBER", "optional": false },
                { "name": "heartRate", "type": "NUMBER", "optional": false }
            ]
         },
         "links": [ "..."]
      }
   ]

A device can implement multiple device models. For example, device models may exist for battery management and for temperature sensing. A single device might implement one or both of these device models.

When a registered device has device models that aren’t defined yet in Oracle Internet of Things Cloud Service, the device can declare these models during activation. These draft device models aren’t usable until they are saved and become normal device models. When draft models are saved, the device that declared them during activation is also updated.

Device models that are included with Oracle Internet of Things Cloud Service are known as system models. These models can’t be changed or deleted.

You can add a device model either from Oracle IoT Fleet Monitoring Cloud Service or from the Oracle Internet of Things Cloud Service platform UI.

Upload Device Models

To create device models, create and upload a comma-separated value (CSV) file with the device model attributes. Upload a separate .csv file for each device model you create.

Note:

Existing data is overwritten when you upload a new .csv file.
  1. Click Menu (Menu icon) and then click App Settings.
  2. Click Upload (Upload tab).
  3. Click Click here to download a sample CSV file for: Device Model in the Import Data dialog box.
  4. Click Save File .
  5. Click OK and browse to a location to save the file.
  6. Click Save.
  7. Browse to the location where you saved the .csv file.
  8. Open the .csv file and complete these fields:
    • DEVICEMODEL: Accept the default device model name (ora_obd2_device_model) if you have not used it previously, or enter a new device model name. Accept the default device model URN (urn:com:oracle:iot:device:obd2) if you have not used it previously, or enter a new URN using this format: urn:com:oracle:iot:device:<my device model name>.
    • ATTRIBUTE: Accept or remove device model attributes. Attributes identified as mandatory cannot be removed. Do not add custom attributes or alerts. Supported attributes include:
      • ora_obd2_vehicle_speed: (Mandatory) The vehicle speed.

      • ora_obd2_engine_rpm:(Mandatory) The vehicle engine revolutions per minute (rpm).

      • ora_obd2_number_of_dtcs: (Mandatory) The number of vehicle diagnostic trouble codes (DTCs).

      • ora_obd2_engine_coolant_temperature: (Mandatory) The vehicle coolant temperature.

      • ora_obd2_throttle_position:(Optional) The vehicle throttle position.

      • ora_obd2_true_odometer: (Optional) The vehicle odometer reading.

        Note:

        When performing distance traveled calculations, this attribute OR the ora_obd2_distance_since_dtcs_cleared attribute must be present. If both attributes are present, the ora_obd2_true_odometer attribute takes precedence.
      • ora_obd2_distance_since_dtcs_cleared: (Optional) The distance the vehicle has traveled since the DTCs were cleared.

        Note:

        When performing distance traveled calculations, this attribute OR the ora_obd2_true_odometer attribute must be present. If both attributes are present, the ora_obd2_true_odometer attribute takes precedence.
      • ora_obd2_total_fuel_used: (Optional) The total fuel used by the vehicle.

        Note:

        When performing fuel consumption calculations, this attribute OR the ora_obd2_runtime_since_engine_start attribute must be present. If both attributes are present, the ora_obd2_total_fuel_used attribute takes precedence.
      • ora_obd2_runtime_since_engine_start: (Optional) The time the vehicle engine has been running since the engine was started.

        Note:

        When performing fuel consumption calculations, this attribute OR the ora_obd2_total_fuel_used attribute must be present. If both attributes are present, the ora_obd2_total_fuel_used attribute takes precedence.
      • ora_obd2_average_fuel_economy: (Optional) The average fuel economy for the vehicle.

        Note:

        When performing average fuel consumption calculations, this attribute OR the ora_obd2_mass_air_flow attribute must be present. If both attributes are present, the ora_obd2_average_fuel_economy attribute takes precedence.
      • ora_obd2_mass_air_flow: (Optional) The vehicle mass air flow value.

        Note:

        When performing average fuel consumption calculations, this attribute OR the ora_obd2_average_fuel_economy attribute must be present. If both attributes are present, the ora_obd2_average_fuel_economy attribute takes precedence.
      • ora_latitude: (Mandatory) The current vehicle latitude. Do not delete this attribute.

      • ora_longitude: (Mandatory) The current vehicle longitude. Do not delete this attribute.

      • ora_altitude: (Optional) The current vehicle altitude.

    • ALERT: Accept or modify these alert attributes:
      • ora_obd2_vehicle_started_alert: (Mandatory) Receive an alert message when a vehicle starts. If you did not accept the default device model URN, modify the alert URN. For example, if the device model URN is urn:com:oracle:iot:device:<my device model name> the alert URN should be urn:com:oracle:iot:device:<my device model name>:vehicle_started.

      • ora_obd2_vehicle_stopped_alert: (Mandatory) Receive an alert message when a vehicle stops. If you did not accept the default device model URN, modify the alert URN. For example, if the device model URN is urn:com:oracle:iot:device:<my device model name> the alert URN should be urn:com:oracle:iot:device:<my device model name>:vehicle_stopped.

      • harshCornering: (Optional) Receive an alert message when a vehicle corners harshly. This alert is used to calculate the driver performance score. If you did not accept the default device model URN, modify the alert URN. For example, if the device model URN is urn:com:oracle:iot:device:<my device model name> the alert URN should be urn:com:oracle:iot:device:<my device model name>:harshCornering.

      • harshAcceleration: (Optional) Receive an alert message when a vehicle accelerates harshly. This alert is used to calculate the driver performance score. If you did not accept the default device model URN, modify the alert URN. For example, if the device model URN is urn:com:oracle:iot:device:<my device model name> the alert URN should be urn:com:oracle:iot:device:<my device model name>:harshAcceleration.

      • harshBraking: (Optional) Receive an alert message when a vehicle brakes harshly. This alert is used to calculate the driver performance score. If you did not accept the default device model URN, modify the alert URN. For example, if the device model URN is urn:com:oracle:iot:device:<my device model name> the alert URN should be urn:com:oracle:iot:device:<my device model name>:harshBraking.

      • overIdling: (Optional) Receive an alert message when a vehicle is stationary and idling. This alert is used to calculate the driver performance score. If you did not accept the default device model URN, modify the alert URN. For example, if the device model URN is urn:com:oracle:iot:device:<my device model name> the alert URN should be urn:com:oracle:iot:device:<my device model name>:overIdling.

      • overSpeeding: (Optional) Receive an alert message when a vehicle exceeds the speed limit. This alert is used to calculate the driver performance score. If you did not accept the default device model URN, modify the alert URN. For example, if the device model URN is urn:com:oracle:iot:device:<my device model name> the alert URN should be urn:com:oracle:iot:device:<my device model name>:overSpeeding.

  9. Save and close the .csv file.
  10. On the Import Data dialog box, for Import Data for select Device Model.
  11. Click Choose File and then browse to the location where you saved the .csv file.
  12. Select the file and then click Open.
  13. Click Import and wait for the upload successful message.
  14. Click Back
    Alternatively, to create a device model in Oracle Internet of Things Cloud Service platform see Create a New Device Model and to add it to Oracle IoT Fleet Monitoring Cloud Service, see Assign a Device Model to a Cloud Service. If you have a JSON file of the device model, you can Import a Device Model and then assign it to Oracle IoT Fleet Monitoring Cloud Service

Device Overview

A device is a data logger that is connected to the OBD-II port of a fleet vehicle or a sensor that reads and transmits real time vehicle data. Vehicle data can include vehicle speed, engine revolutions per minute (rpm), vehicle diagnostic trouble codes (DTCs), coolant temperature, latitude, and longitude.

The data logger transmits location and operational data to Oracle Internet of Things Cloud Service. The device model determines what data is sent from Oracle Internet of Things Cloud Service to Oracle IoT Fleet Monitoring Cloud Service.

To associate ensors with your vhicles, make sure that the devices are registered and activated in Oracle Internet of Things Cloud Service. Oracle IoT Fleet Monitoring Cloud Service relies on Oracle Internet of Things Cloud Service for its devices. If you do not already have your sensor devices set up in Oracle Internet of Things Cloud Service, you need to register and activate these devices.

Register a Single Device

To communicate with Oracle Internet of Things Cloud Service, every device that is connected to Oracle Internet of Things Cloud Service must be registered and then activated. All devices are registered as a Directly Connected Device (DCD). During activation, the device indicates support for indirect enrollment. A device indicating indirect enrollment capability is automatically changed from DCD to Gateway.

  1. Open the Oracle Internet of Things Cloud Service Management Console. The URL format to access the IoT management console is: <iot instance name>.<domain name>/ui. For example: https://myiotcs.mydomain.oraclecloud.com/ui.
  2. Click the Menu (Menu icon) icon adjacent to the Oracle Internet of Things Cloud Service title on the Management Console.
  3. Click Devices.
  4. Click Registration.
  5. Click Register Single Device.
  6. Complete the optional and mandatory fields.

    Note:

    If you leave the Activation Secret field blank, a value is auto-generated and displayed when the device registration is confirmed. You can enter your own Activation Secret value. Any additional information, such as Name, Description, and Metadata are optional, but can be useful as search criteria when managing your registered devices.
  7. Click Register.
  8. (Optional) Click Select Devices to Provision and select one or more indirectly connected devices to provision the gateway with the shared secret credentials of the selected devices.

    Indirectly connected devices that use controlled roaming can connect through a gateway only if the gateway has the shared secret credentials to activate the device.

  9. Enter a password in the File Protection Password field to encrypt the provisioning file that contains the configuration and credentials to activate your device.
  10. Enter the password again in the Confirm Password field.
  11. Click Download Provisioning File to download the provisioning file to your computer.
    The provisioning file is required to run your client.
  12. Click Finish.
  13. Click Management .
    The registered device is listed in the Management pane with a State value of Registered and Type value of Unknown.

    See Cloud Service Device Life Cycle, and Locate a Device for more information about device states, types, and managing your devices.

Register a Batch of Devices

You can register a batch of devices that you want to connect to Oracle Internet of Things Cloud Service using a comma-separated values (CSV) file.

For information about CSV file properties, see About CSV Batch Registration File Properties.
  1. Open the Oracle Internet of Things Cloud Service Management Console. The URL format to access the IoT management console is: <iot instance name>.<domain name>/ui. For example: https://myiotcs.mydomain.oraclecloud.com/ui.
  2. Click the Menu (Menu icon) icon adjacent to the Oracle Internet of Things Cloud Service title on the Management Console.
  3. Click Devices.
  4. Click Registration.
  5. Select one of these options:
    • Click Download CSV template to download a CSV template that you can complete.

      Note:

      The CSV file contains the mandatory and optional property values for each device. If a value is not provided for the optional properties, insert a comma to indicate that a value is not provided. In the last line of the sample CSV file, a comma indicates that property values are not provided for ActivationId and Activation Secret
    • Click Batch Registration to upload an existing CSV file.
  6. Click Browse and browse to the CSV file that contains the registration information for the devices you are registering.
  7. Click Next when the CSV registration file is successfully uploaded.
    If the Review page contains a warning (A yellow triangle with an exclamation point. This icon is used if there is at least one device in the CSV file that is already registered) icon, select one of these options:
    • Update - Choose this option if you want to update the information for an existing registered device. The registered device has the same manufacturer, model and serial number as one of the devices listed in the CSV registration file.
    • Ignore - Choose this option if you do not want to include the device in the current registration process.
  8. Click one of these options:
    • Next - Click to proceed to register the items in the CSV registration file that have been identified as being viable candidates for registration.

    • Cancel - Click to discontinue the current batch registration process.

  9. Enter a password to encrypt the provisioning file that contains the configuration and credentials to activate your device.
  10. Enter the same password in the Confirm Password field.
    If both passwords match the Download Provisioning File button becomes enabled.
  11. Click Download Provisioning File to download the provisioning file to your computer.
    You will need this file to run your client.
  12. Click Finish.
  13. Click Management on the left menu.
    The registered devices are listed in the Management page and have the state of Registered.
  14. Activate the registered devices to begin a secure communication between the devices and Oracle Internet of Things Cloud Service. See Activating a Batch of Registered Devices.

About CSV Batch Registration File Properties

The following table provides descriptions of the properties that appear in the Comma Separated Values (CSV) file used to register a batch of devices with Oracle Internet of Things Cloud Service. Mandatory and optional values are described in the table and are listed in the order they are expected to appear in the CSV file.

To register a batch of devices with Oracle Internet of Things Cloud Service, see Register a Batch of Devices.

Property Required / Optional Description

Name

Optional

The String data type assigned to the registered device. This value can be modified after device registration.

Manufacturer

Required

The manufacturer of the device.

Model Number

Required

The model number of the device

Serial Number

Required

The serial number of the device.

Activation ID

Optional

A Device Unique Identifier (UID) that is required for device activation. If a value is not specified, an auto-generated value is assigned to the device after a successful registration. The value cannot be changed after the device is successfully registered.

Activation Secret

Optional

The Activation Secret (also known as Shared Secret) value required to activate your device. If a value is not specified, an auto-generated string value is assigned to the device after a successful registration. This value is available after a successful registration. This value can be modified before you modify your device.

Latitude

Optional

The decimal notation of the latitude of the device’s position. For example: -43.5723 [World Geodetic System 1984]. If you specify the latitude, then you must also specify the longitude.

Longitude

Optional

The decimal notation of the longitude of the device’s position. For example: , e.g. -43.5723 [World Geodetic System 1984]. If you specify the longitude, then you must also specify the latitude.

Altitude

Optional

The decimal notation of the altitude of the device’s position, in meters above sea level.

Accuracy

Optional

The accuracy of the device’s position in meters. This must be a positive number or zero. An accuracy value can only be specified if the latitude and longitude are provided.

Metadata

Optional

Key/value pairs that are listed in successive columns. There must be an even number of columns containing keys and values. If there is an odd number of columns, an error message is returned.

Activate a Device

A device can be activated after it is registered and an application has been created and run on the device. During activation, the device indicates support for indirect enrollment. A device indicating indirect enrollment capability is automatically changed from DCD to Gateway.

  1. Register your directly connected device. See Registering a Single Device.
  2. Create an application for the device using the Oracle Internet of Things Cloud Service Client Software Library APIs. See Developing Device Software Using the Client Software Libraries.

    When using the Java Client Library, for example, use the following steps to initialize and activate the device:

    1. Add this statement to the device application code to initialize the device:

      DirectlyConnectdDevice dcd = new DirectlyConnectedDevice(configFilePath, configFilePassword);
    2. Add this statement to the device application code to activate the device:

      if (!dcd.isActivated())
      { dcd.activate(deviceModelUrn); }
  3. Verify the device has been activated:
    1. Open the Oracle Internet of Things Cloud Service Management Console.
    2. Click the Menu (Menu icon) icon adjacent to the Oracle Internet of Things Cloud Service title on the Management Console.
    3. Click Devices.
    4. Click Management.
    5. Locate the device in the device table or use the Property and Value fields at the top of the table to search for a specific device.
    6. Verify Activated and not Registered is displayed in the State column.

Activating a Batch of Registered Devices

After you’ve registered a batch of devices, you need to activate the devices before they can securely communicate with Oracle Internet of Things Cloud Service.

  1. Register the devices and download the provisioning file. See Registering a Batch of Devices.
  2. Activate each of the registered devices. See Activate a Device.
  3. Verify that each of the registered devices has been activated.
    1. Open the Oracle Internet of Things Cloud Service Management Console.
    2. Click the Menu (Menu icon) icon adjacent to the Oracle Internet of Things Cloud Service title on the Management Console.
    3. Click Devices.
    4. Click Management.
    5. Locate the device in the device table or use the Property and Value fields at the top of the table to search for a specific device.
    6. Verify Activated and not Registered is displayed in the State column.

Install the Sample Application for Testing

To view and monitor simulated vehicle data, you install a sample application on a mobile device. The sample application displays simulated vehicle data such as coolant temperature and throttle position. The sample application can help you determine what vehicle data to include in your own application.

  1. Make sure the hardware prerequisites are met before you install the Java SE client software library on your directly connected device. See Oracle IoT Cloud Service Client Software Certified System Configurations.
  2. Make sure that the time in your system is current. If it isn’t, update it using the date command. The following shows an example of setting the time on a Linux platform:
    date -s "15 FEB 2016 14:00:00"
  3. Prepare your directly connected device to use the Java SE client software library:
    1. Open a web browser and browse to Oracle Java SE Embedded Downloads.
    2. Download Oracle Java SE Embedded JDK Version 8 to your device. These are the available versions:
      Platform Hardware File
      Linux/x86 desktop x86 Linux Small Footprint – Headless

      ejdk-8u101–linux-i586.tar.gz

      Raspberry Pi or i.MX6 boards ARMv6/ARMv7 Linux - VFP, HardFP ABI, Little Endian1 version.

      ejdk-8u101-linux-armv6-vfp-hflt.tar.gz

    3. Run this command to extract the contents of the Oracle Java SE Embedded JDK file:
      cd <eJDK-download-folder-location>/
      tar xzvf ejdk-8u73-linux-armv6-vfp-hflt.tar.gz
    4. Verify that the ejdk1.8.0_73 folder was created.
    5. Run this command to create the Java SE Embedded Compact 2 profile:
      cd ejdk1.8.0_73/bin
      ./jrecreate.sh -d /home/janeuser/ejre1.8.0_73_compact2_minimal_vm -p compact2 --vm minimal
      The output should appear similar to this example:
      Building JRE using Options {
      ejdk-home: /home/janeuser/ejdk1.8.0_73
      		dest: /home/janeuser/ejre1.8.0_73_compact2_minimal_vm
      		target: linux_arm_vfp_hflt
      		vm: minimalruntime: compact2 profile
      		debug: false
      		keep-debug-info: false
      		no-compression: false
      		dry-run: false
      		verbose: false
      			extension: []}
    6. Install the JDK Compact 2 profile on your device. See Create Your JRE with jrecreate in the Oracle Java SE Embedded Developer’s Guide.
  4. Register your directly connected device and download the provisioning file. See Registering a Single Device.
  5. Open a web browser and browse to the Oracle Internet of Things Cloud Service client software libraries download site.
  6. Scroll to Java SE Client Software Library and download the Binaries and Samples zip files from the Java SE Client Software Library table. This table describes the contents of each zip file:
    Filename Description
    iotcs-csl-javase-bin-<version>.zip

    Contains the Java SE client software library binary files.

    iotcs-csl-javase-samples-<version>.zip

    Contains the Java SE sample applications.

  7. Extract the contents of the zip files. The files are saved to these directories:
    Filename Directory
    iotcs-csl-javase-bin-<version>.zip iotcs/csl/ios/bin
    iotcs-csl-javase-samples-<version>.zip iotcs/csl/ios/samples
  8. Associate the FleetMonitoringOBD2Device device model with the Obd2DeviceSample application. See Associate a Device Model to an IoT Application.
  9. Set the CL_HOME, GRADLE_HOME, and, JAVA_HOME environment variables to the values listed in this table:
    System Variable Name Example
    CL_HOME /home/user/iotcs/csl/javase/
    GRADLE_HOME /opt/gradle-<version>
    JAVA_HOME /usr/java/jdk<version>
  10. Modify the PATH variable to include the path to the Java and Gradle executables.
    For example, in the Linux environment, you can add the following to the existing PATH variable.
    export PATH=$JAVA_HOME/bin:$GRADLE_HOME/bin:$PATH
  11. If your computer is on a Virtual Private Network, or behind a firewall:
    1. Open the gradle.properties file, located in the Gradle user home directory and add these lines:
      systemProp.http.proxyHost=<your_proxy_server.com>
      systemProp.http.proxyPort=<your_proxy_port>
      systemProp.https.proxyHost=<your_proxy_server.com>
      systemProp.https.proxyPort=<your_proxy_port>
    2. Save your changes and close the gradle.properties file.
  12. Open a command prompt and browse to the location of the sample OBD-II application.
  13. Run this command to create the OBD-II simulator device model:
    curl --user <IOT_POD_LOGIN>:<IOT_POD_PASSWORD> https://<IOT_POD_SERVER>:<IOT_POD_PORT>/iot/api/v2/deviceModels -k -X POST -d @tmp/Obd2Simulator.json -H "Content-Type:application/json"
    Replace IOT_POD_LOGIN, IOT_POD_PASSWORD, IOT_POD_SERVER, and IOT_POD_PORT with the values for your environment.
  14. Run this command to start the Obd2DeviceSample application:
    java -cp "./samples/build/libs/iotcs-csl-samples.jar:lib/device-library.jar:library/shared/lib/json-20160212.jar" com.oracle.iot.sample.obd2.Obd2DeviceSample<provisioner file> <password>
    Replace provisioner file and password with the values you recorded when you registered your device.
    Output similar to the following appears:
    DEDF23F9-4D8A-4FDC-A8F3-9C06C6BD5D11
    !!! ALERT: Vehicle started Event: speed: 10
    17:30:57: Speed: 0 Throttle: 0.00% RPM: 0.00 CoolantTemp:-40 FuelRate: 0.00 FuelEconomy: 0.00 FuelTank: 99.99% Runtime: 1 Distance: 0.00 Location : 12.897532, 77.658337 800.000000
    17:30:58: Speed: 2 Throttle: 0.78% RPM: 128.50 CoolantTemp:-38 FuelRate: 25.70 FuelEconomy: 0.04 FuelTank: 99.98% Runtime: 2 Distance: 0.00 Location : 12.897534, 77.658337 800.000000
    17:30:59: Speed: 3 Throttle: 1.18% RPM: 192.75 CoolantTemp:-37 FuelRate: 38.55 FuelEconomy: 0.05 FuelTank: 99.97% Runtime: 3 Distance: 0.00 Location : 12.897535, 77.658337 800.000000
    

Set Up a Freematics One Vehicle Data Logger for Testing

To view and monitor vehicle data sent by a Freematics One vehicle data logger, you install a sample application on an Android device. The sample application displays vehicle data such as coolant temperature and throttle position. Vehicle data is sent from the Freematics One vehicle data logger to the Android device, and then to Oracle IoT Fleet Monitoring Cloud Service. The sample application can help you determine what vehicle data to include in your own application.

  1. Register your directly connected Android device and download the provisioning file. See Registering a Single Device.
  2. Install the provisioning file on the Android device.
  3. Set up your development environment to use the Android client software libraries. See Setting Up Your Development Environment to Use the Android Client Software Libraries.
  4. Prepare your device to use the Android client software libraries. See Preparing Your Device to Use the Android Client Software Libraries.
  5. Install the sample Android APK application on the Android device. See Running the Sample Android Directly Connected Device Application.
    The sample Android APK application is included with the Android client software libraries you downloaded and extracted in step 3.
  6. Update the Freematics One vehicle data logger firmware to match the Oracle IoT Fleet Monitoring Cloud Service device model Parameter IDs (PIDs):
    1. On a computer, open a web browser and browse to the Arduino website.
    2. Download install the latest Arduino IDE.
    3. Open Git CMD and run this command: git clone https://github.com/stanleyhuangyc/Freematics.git.
    4. Run these commands: cd Freematics and then git checkout 98eccfba5ae3101e1a96b8d3d446c0a6a0b17b1e.
    5. Browse to the location of the Freematics datalogger.ino file. For example: C:\Users\<usernname>\Downloads\FreematicsNew\Freematics\firmware_v4\datalogger.
    6. Open the datalogger.ino file in a text editor.
    7. On line 326 remove the pids[2] array and all references to it.
    8. Enter these values for the byte pids[] array: PID_SPEED, PID_RPM, PID_THROTTLE, PID_MAF_FLOW, PID_FUEL_LEVEL, PID_RUNTIME, PID_DISTANCE, and PID_COOLANT_TEMP and then save and close the datalogger.ino file.
    9. Copy the libraries folder from the Freematics file into the Arduino libraries folder. Typically, the Arduino libraries folder is located at this path: C:\Users\<usernname>\Documents\Arduino\libraries.
    10. Connect one end of a data cable into the Freematics One vehicle data logger and the other end of the data cable into the computer.
    11. Open a web browser and browse to the Silicon Labs website.
    12. Download and install the USB to UART Bridge Virtual COM Port (VCP) drivers.
    13. Open Windows Device Manager, expand Ports (COM & UPI), and then record the port number for Silicon Labs CP210x USB to UART Bridge (COM30).
    14. Open the Arduino IDE.
    15. Click File and then Open and then browse to the location of the datalogger.ino file that you modified in steps h to k.
    16. Click Tools and then Port and confirm the port number you recorded in step h is displayed. If you cannot access the Port menu, close and reopen Arduino or restart the computer.
    17. Click Tools and then Serial Monitor and confirm that data is scrolling in the window
    18. Click Sketch and then Verify/Compile.
    19. Click Sketch and then Upload.
  7. Insert the Freematics One vehicle data logger into a vehicle OBD-II port.
  8. Activate Bluetooth functionality on the Android device.
  9. Start the vehicle in which the Freematics One vehicle data logger is installed.
  10. Move the Android device to the interior of the vehicle and connect to the Freematics One vehicle data logger.
  11. Open the sample Android APK application on the Android device.
    To learn more, complete the Set Up a Freematics ONE Vehicle Data Logger tutorial.