Remotely configuring the KeepTruckin Electronic Logging Device

Background

The primary product offering of KeepTruckin (till date) is an Electronic Logging Device (ELD). KeepTruckin ELD is a hardware device which is attached to an existing port in the truck and is used to track all vehicle data. Multiple hardware versions of the device have been launched so far making it powerful and feature-rich in each iteration. Starting with hardware v3.2ca, the device can be directly connected to the internet (in the prior versions, the device had to be paired with the mobile phone).

Bringing KeepTruckin ELD online is a huge step forward because now the device could do a lot of stuff directly for which it previously had to depend on a mobile phone and a Bluetooth connection. A sweet thing is the ability to connect the device to AWS Internet of Things (AWS IoT).

Leveraging AWS IoT, KeepTruckin recently launched a feature that provides an ability to our customers to configure the device remotely. The features on the device can now be turned off/on or tuned further. Setting up WiFi Hotspot on the KeepTruckin ELD is one such example.

Engineering

The two possible workflows for the remote device configuration are:

Init (when KeepTruckin ELD is not yet registered in AWS IoT)

Each KeepTruckin ELD is provisioned into our database before dispatching it to a customer. This provisioned data which includes various device attributes and a default device configuration is accessible over a REST API via our application services*.

Once the customer receives the device and turns it ON for the first time:

• the device connects to the AWS IoT
• based on an existing AWS IoT rule, an AWS Lambda is triggered. We call it Just in time Registration (JITR) lambda
• the JITR lambda makes a REST API call to our backend services to fetch the device provisioning data and registers the device with the AWS IoT creating an AWS IoT Thing (Thing). The device configuration is set as a part of Thing’s shadow in the desired section. One of the examples of the shadow is:

"desired": {
    "config": {
      <snip>
      "eld_config_version": <eld-config-version>,
      "wifi_hotspot_mode": <wifi-mode>,
      "wifi_hotspot_passphrase": <wifi-passphrase>,
      "wifi_hotspot_ssid": <wifi-ssid>,
      <snip>
    },
  <snip>
  },

• all of the fields shown above have a default value which could be changed by the customer anytime via KeepTruckin admin portal, except eld_config_version which is managed by KeepTruckin application service
• this finishes off the device registration in our backend infrastructure
• the firmware on KeepTruckin ELD which includes AWS IoT Device SDK gets notified about the AWS IoT artifacts and downloads the Thing’s shadow, updates the device configuration locally, restarts the device (if applicable) and updates the configuration on the device side to the reported section of the Thing’s shadow marking the final step in this workflow as complete*

This workflow is shown in Fig 1 below:

Fig 1. Init workflow

Update (when KeepTruckin ELD is already registered in AWS IoT)

KeepTruckin admin portal provides an ability to our customers to configure a device as per their requirements. Whenever a device configuration is changed, for eg, WiFi Hotspot is turned off or its credentials are changed, the update workflow kicks in as follows:

• KeepTruckin admin portal executes a REST API call to our application services to update the device configuration in our database. A new ELD config version is created in the database to reflect this change
• the application services then dispatch a payload to AWS Simple Queue Service (SQS) in a dedicated queue. The payload contains key-value pairs like device identifier and updated device configuration
• a new entry in the SQS queue triggers shadow-updater lambda which parses the payload from SQS queue to extract the device identifier and the updated configuration. The lambda fetches the Thing for the device identifier and pushes the received configuration in the Thing’s shadow in the desired section
• on the shadow update, shadow-pusher lambda is triggered which adds the Thing for the device identifier to an AWS IoT Thing Group (Thing Group) named configPush (Thing Group is created if not found)
• as soon as the Thing is added to configPush Thing Group, new job execution is queued in an AWS IoT Continuous Job named configPush (the continuous job is created if not found)
• the device firmware whose WiFi Hotspot configuration is changed above is notified about the new job execution. The firmware fetches the job document attached to the job execution to read a key calledtype. If the value of this key is set aseldconfig the firmware realizes that there is a new ELD config version available to be downloaded from the Thing’s shadow onto the device
• once downloaded, the firmware applies the new ELD config version on the device and updates the reported section of the Thing’s shadow marking the final step in the process as complete

This workflow is shown in Fig 2 below:

Fig 2. Update workflow

Tip 1: In the shadow-pusher lambda, one could choose to create a snapshot job every time a Thing’s shadow is updated. However, AWS IoT restricts creating more than 1000 snapshot jobs. That’s why we designed the above solution using a continuous job and a Thing Group.

Tip 2: Although they sound similar, job execution is different from a job

Wrap Up

KeepTruckin is an AWS shop and leveraging AWS we are able to roll out new features at a pretty fast pace. This makes working at KeepTruckin an engaging and fun experience. If you are interested in learning more about the opportunities at KeepTruckin, do check out our Careers page.

* details on how the device data is maintained on the application side and how the device firmware deals with AWS IoT is out of scope for this post