Use location data with AWS IoT Device Management to monitor and manage your IoT fleet

As the number of Internet of Things (IoT) devices increase exponentially, enterprises need advanced tools that can leverage location data to manage their IoT fleets across different geographies. Knowing your devices’ location is important not only for asset management and theft detection, but also to dispatch timely remediation when your devices are non-operational. Moreover by combining location and device state metadata, you can derive richer insights about your IoT fleet, such as detecting location-specific connectivity issues or understanding usage trends by location. As an example, if you operate vending machines or advertisement kiosks, you can prioritize fleet expansion, upgrades, or advertisements based on the geographic locations associated to higher user interaction.

With AWS IoT Device Management’s location indexing and geoquery feature, you can search for devices based on their last reported location. You can also leverage location information to enhance your IoT fleet management and monitoring activities. This location indexing and geoquery feature allows you to list devices that are located within a specific geographic area, perform a proximity search relative to a reference location, implement targeted over-the-air (OTA) updates, derive location-specific device performance insights, and identify devices that are no longer in a desired geographic boundary.

In this blog, you will learn how to get started with indexing location data and using geoqueries to support your day-to-day IoT fleet management operations.

Fleet Indexing and Geoquery Overview

AWS IoT Device Management is a fully managed cloud service that you can use to remotely monitor and manage your IoT devices at scale. It’s Fleet indexing capability allows you to index, search, aggregate, and group your devices based on any combination of connectivity and device state, metadata stored across the following IoT data sources: AWS IoT registry, AWS IoT Device Shadow, AWS IoT connectivity, AWS IoT Device Management Software Package Catalog, and AWS IoT Device Defender violations. With location indexing and geoqueries, you can narrow your searches by location for specific insights and monitoring.

Figure 1: Reference architecture for ingesting, indexing, and consuming location information using AWS IoT Device Management.

Figure 1 depicts a reference architecture to ingest, index, and consume location information using AWS IoT services. To use location data in searches, you must store your device’s geolocation information (latitude and longitude) in the classic shadow or named shadow and enable location indexing in AWS IoT Core Settings. Geolocation information can be stored in one of the four supported location data formats (for more information, see supported data formats ). For devices that don’t have built-in global positioning system (GPS), you can use AWS IoT Core’s Device Location feature to resolve the location of the device. Then you can use the AWS IoT Rules Engine to store the location to the device into its classic shadow or named shadow. Once the location data is indexed by IoT Device Management service, it can be used by multiple downstream applications such as to monitor the device fleet’s aggregate state in Amazon CloudWatch, to query nearby devices using Amazon API Gateway or to analyze and generate location based insights for the device fleet.

Geoqueries use fleet indexing’s existing search and aggregation APIs with an additional ‘geodistance’ input parameter. This geodistance parameter specifies a search radius boundary from the specified latitude and longitude coordinates. Geoqueries can be combined with fleet metrics and Amazon CloudWatch to analyze trends over time and create alarms to monitor the state of your fleet based on pre-defined thresholds. Other examples include, finding the number of e-bikes available at a given time in a high-demand location, monitoring the availability KPIs for the electric vehicle (EV) chargers, being alerted when a device moves from its installed location, reporting the payment terminal locations to regulatory bodies, generating location-sensitive insights about solar cell performance, diagnosing device malfunctions caused by geo-influenced factors (such as temperature and humidity).

Getting started with geoqueries

The following sections explore some of the geoqueries capabilities. In these walk-throughs, you develop a system for an EV public charging infrastructure global provider. This example provides EV chargers with different connecter types, power ratings, and charging speeds. Using geoqueries, you can address the following business requirements:

1. Near real-time ability to discover chargers in nearby locations.
2. Monitor the number of available chargers to ensure a specific service level availability (SLA).
3. Find the distribution of EV charger type (Level 1, Level 2, and Level 3 – representing different charging speeds) that exceed a specific daily transaction volume.

Prerequisites

Before completing the following steps, you must have:

1. An AWS account with access and permission to perform the actions on AWS IoT Core and AWS IoT Device Management.
2. AWS Identity and Access management (IAM) permissions to create and assign roles in AWS IoT Core.
3. Access to AWS CloudShell, and basic knowledge of Linux and using the AWS Command Line Interface (AWS CLI).

Walkthrough

Initial setup and config

In this section you create a set of things in AWS IoT Core to represent the EV chargers. The scripts and code use the us-east-1 Region. The script creates a thing and generates associated meta-data related to charger specification. It also generates a named shadow, chargerusage, that contains data about the charger location and its usage. You should use CloudShell in us-east-1 to create the initial setup and run the geoqueries.

1. Login to the AWS Management Console and open CloudShell.
2. Issue the following to clone the git repository to download scripts.

$ git clone https://github.com/aws-samples/aws-iot-device-management-geoquery.git

3. Run the createResources.sh script to create a fleet of EV chargers.
   If you use the parameters as provided in the commands below, you will have 10 things named as geoquery-test-<n> in AWS IoT Core. The script also generates some temporary files that are stored in the local directory and are used by subsequent scripts.

$ cd aws-iot-device-management-geoquery
$ bash createResources.sh geoquery-test 10

Note: Ignore following error if you see it in the output

An error occurred (ResourceAlreadyExistsException) when calling the CreatePolicy operation: Policy cannot be created - name already exists (name=blog_fi_geoquery_policy)

4. Run updateShadows.sh script to update the things’ shadow documents.

$ bash updateShadows.sh

Configure Fleet Indexing

1. Go to AWS Management Console and search for AWS IoT Core.
2. In AWS IoT Core (us-east-1 Region), choose Settings in the configuration pane.
3. Go to the Fleet indexing section and choose Manage indexing.
   1. Select the checkboxes for Thing Indexing and Add thing connectivity.
   2. Select the checkbox for Add named shadows. If you do not see chargerusage listed under the Named shadow selection, select Browse shadow names by thing.
   3. Choose one of the things that were created in the previous section.
   4. Select chargerusage from the list and select Add shadow names.
4. Navigate to Index location data and choose Add new field.
   1. Add shadow.name.chargerusage.reported.config.location under Data path.
   2. Select Lat, long from the Sequence dropdown list.
5. Navigate to Custom fields for aggregation and select Add new field.
   1. Add attributes.type under Field Name and select String from the Field Type dropdown list.
   2. Navigate to the bottom of screen and select Update.
6. Check the status of index by running following command.

$ aws iot describe-index --index-name "AWS_Things" --region us-east-1

Wait until indexStatus is ACTIVE.

Figure 2: AWS IoT Core settings to enable fleet indexing

Use case 1: Proximity search 

In this section, you use the SearchIndex API to demonstrate how vehicle owners can find nearby chargers suitable to their EV. This example’s assumption are as follows:

• The vehicle supports Level 1 and Level 2 electric chargers.
• The vehicle is aware of its current location’s latitude and longitude (37.723028, -122.375811) through onboard GPS modules.
• The vehicle owner wants to search for a suitable charger within a 15 mile radius of the vehicle’s current location.

1. Goto CloudShell you used in previous steps.
2. Issue the following command on the command prompt.

aws iot search-index \
--index-name "AWS_Things" \
--region us-east-1 \
--query-string "( \
    attributes.type:Level_1 OR 
    attributes.type:Level_2) AND 
    shadow.name.chargerusage.reported.usage.isOnline:true AND 
    shadow.name.chargerusage.reported.config.location:geo_distance,37.723028,-122.375811,15miles" 

3. The JSON format output lists of all chargers meeting the query criteria. Following is a truncated output for reference. The values in output may vary.

Figure 3: Output of search-index query

Use Case 2: Location-specific fleet monitoring
In this step, you use the fleet indexing fleet metrics feature to monitor the number of operational EV chargers in the geography of interest.

1. Goto CloudShell you used in previous steps.
2. Issue the following command on the command prompt to set up a fleet metric. Once created, this fleet metric generates a data point every 60 seconds, providing the count of chargers that are within a 50 mile radius of San Francisco, CA (37.723028,-122.375811) and are disconnected.

aws iot create-fleet-metric \
--metric-name "OfflineChargers" \
--region us-east-1 \
--query-string " shadow.name.chargerusage.reported.usage.isOnline:false AND \ 
    shadow.name.chargerusage.reported.config.location:geo_distance,37.723028,-122.375811,50miles" \
--aggregation-type "name=Statistics,values=count" \
--aggregation-field "registry.version" \
--period 60

3. Once the fleet metric is setup, you can view the OfflineChargers metric sent to CloudWatch every minute.
4. You can also setup CloudWatch alarms against this metric. For the steps to create these alarms, see View fleet metrics in CloudWatch. When the alarm threshold that is configured in CloudWatch is crossed, multiple notifications and ticketing-related actions are triggered to alert the maintenance teams. You can create additional fleet metrics using different query criteria using the same process.

Use case 3 : Location-specific aggregated information/insights

In this section, you use the GetBucketsAggregation API to see the distribution of chargers based on their type (Level_1, Level_2 and Level_3) that are above a given daily transaction threshold.

1. Goto CloudShell you used in previous steps.
2. Issue the following command on the command prompt. The query aggregates the chargers that are within a 50 mile radius of San Francisco, CA (37.723028,-122.375811) and had more than 25 transactions a day.

aws iot get-buckets-aggregation \
--index-name AWS_Things \
--region us-east-1 \
--buckets-aggregation-type "termsAggregation={maxBuckets=5}" \
--query-string "shadow.name.chargerusage.reported.usage.dailySessions> 25 AND shadow.name.chargerusage.reported.config.location:geo_distance,37.723028,-122.375811,50miles" \
--aggregation-field "attributes.type"

3. Your output should be similar to Figure 4 below. This image depicts how many Level_1, Level_2, and Level_3 chargers meet the criteria. The ‘count’ may vary on your deployment.

Figure 4: Output of GetBucketAggregation query

Cleaning up

Once you have completed these exercises, do the following to avoid incurring additional costs:

1. If you do not need fleet indexing any longer, turn it off.

1. 1. In AWS IoT Core (us-east-1 Region), navigate to the left side menu, select Settings  
   2. Navigate to Fleet indexing section and select Manage indexing
   3. Unselect checkboxes for Thing indexing
   4. Navigate to the bottom of screen and select Update
2. Run the cleanupResources.sh script to delete the AWS IoT things that you created.

$ bash cleanupResources.sh

Conclusion

In this post, you learned how to use geolocation data with AWS IoT Device Management to search and monitor your device fleet. You learned how to configure the fleet indexing to index fleet device location data, use indexed location data to derive insights, and use fleet metrics to monitor your fleet and view their trends. You can extend this example to update the charger shadow (location, usage, and availability data) dynamically by modifying ShadowClient.py (found in aws-iot-device-management-geoquery directory of the cloned github project), run location-based analytics on fleet data to identify location-based disconnection patterns, or target OTA updates to devices in specified geographic boundaries. You can further explore AWS IoT Core Device Location’s location resolution capability to resolve GNSS/Wi-Fi/Cellular metadata to geolocation, and subsequently index the geolocation data to use geoqueries. To learn more, see Indexing location data in the AWS IoT Developer Guide, or login to the console to get started.

Author bio