# Send Device Location Data to Amazon Location Service Using Beam

Track devices using an Amazon Location Service Tracker.

## Introduction

Amazon Location Service is a useful AWS service that allows you to store and process position updates from your devices.

In a normal scenario you may have to configure each individual device with its own credentials to connect to AWS, as well as consume extra battery power to encrypt that data before it is sent.

With Soracom Beam, you can solve both of these issues by storing AWS credentials in the Soracom User Console and allowing Beam to encrypt your data in the cloud before its transmission to AWS.

Using Beam provides the following benefits:

- No need to install AWS credentials on the device to send data to your Tracker.
- Devices can send location and other data to your Tracker simply by specifying and accessing a Beam entry point. There is no need for the device to go through the Signature version 4 signing process.

> [!NOTE]
>
> Note that this guide uses Soracom Beam's Website entry point in order to send location data. Beam's HTTP entry point cannot be used.

This guide will show you how to configure Amazon Location Service to allow Soracom Beam to send data to an Amazon Location Service Tracker (hereafter "Tracker") in your AWS account.

### Prerequisites

For successful completion of this process the following items are necessary:

- A Soracom account with a Soracom IoT SIM or a Soracom Arc Virtual SIM.
- A device capable of running Python, such as a RaspberryPi.
- Your device should also be configured to connect to a cellular network using a Soracom IoT SIM, or configured to connect to Soracom using Soracom Arc.
- That your device can obtain GPS data (latitude and longitude) by itself.
- An AWS account.
- Your AWS account ID.

## Create an AWS IAM Role for Beam

### 1. Create an IAM Role

First, create an IAM role in your AWS account. We will configure this role with specific permissions that will allow Soracom Beam to access Amazon Location Service.

1. Sign in to your AWS account and open the **[IAM console](https://console.aws.amazon.com/iam/)**.

2. Click **Access Management**, click **Roles**, and then click **Create Role**.

   ![Create Role button in IAM console](https://docs.soracom.io/_astro/create-role.DHxtwZ4z_Z1SodNd.webp)

3. Click **AWS Accounts**, then **Another AWS Account**, and enter one of the following Soracom AWS account IDs that corresponds to the coverage type of your Soracom IoT SIM in the **Account ID** field:

   - Global Coverage: `950858143650`
   - Japan Coverage: `762707677580`

   ![AWS Account ID configuration for Soracom](https://docs.soracom.io/_astro/aws-account.C0Q5IAwc_ZYpDHB.webp)

4. Click the **Require external ID** checkbox and enter any string in the **External ID** field, such as `External-ID-abcdefgh12345678`. Make a note of this **External ID** as we will use it later.

   ![External ID configuration field](https://docs.soracom.io/_astro/external-id.czg60AI3_JwYBa.webp)

> [!WARNING]
>
> For more information on external identities, see [How to use an external ID when granting access to your AWS resources to a third party - AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html).

---

### 2. Create a Policy

Next, we need to create a policy which will allow this role to access Amazon Location Service.

5. Click **Next**. The **Add Permissions** screen will appear.

6. Click **Create Policy**.

   ![Create Policy button in IAM](https://docs.soracom.io/_astro/create-policy.8lM8jIfK_OlIr0.webp)

   In a separate window or tab, the **Create Policy** screen will appear.

> [!NOTE]
>
> When you are done with the **Create Policy** screen, come back to the **Add Permissions** screen where you see **Create Policy** and continue with the creation of the IAM role. Do not close the screen!

7. Set the following fields:

   - Click **Select Service** and click **Location**.

   - Check the following permissions. You can filter by entering the following strings in the **Filter Action** field.

     - **GetDevicePositionHistory**
     - **TagResource**
     - **BatchUpdateDevicePosition**
     - **CreateTracker**
     - **UpdateTracker**

   ![Policy permissions configuration](https://docs.soracom.io/_astro/permissions.DEGYLGIK_2ax9FX.webp)

8. Click on **Resources > Specific > Add ARN** under **tracker**. The **Add ARN** screen will appear.

   ![Resource ARN configuration](https://docs.soracom.io/_astro/ARN.B0SZBPFc_ZGU89w.webp)

9. Under **Specify ARN for tracker**, enter the Amazon Location Service ARN for your AWS account (e.g., `arn:aws:geo:us-east-1:900012345678:tracker/*`). Ensure that you use the correct region in the ARN string and the **Region** field. Then click **Add**.

   ![ARN settings dialog for Amazon Location Service tracker](https://docs.soracom.io/_astro/arn-settings.BR9LJDt2_22wbmJ.webp)

   Return to the **Create Policy** screen.

10. Click **Next: Tags**, then **Next: Review**.

11. Enter a name for the AWS IAM policy (e.g. `beam-tracker-role`) in **Name** and click **Create Policy**.

    ![Policy name configuration field](https://docs.soracom.io/_astro/name-policy.CJ6zXuHw_Z205oMu.webp)

    An AWS IAM policy will be created and the policy screen will appear.

---

### 3. Add the Policy to the IAM Role

With the policy created, we can now add it to the IAM role.

12. Close the window or tab in which the policy screen is displayed to return to the **Add Permissions** screen.

13. Click on the refresh button, then click on serach field, type the name of the AWS IAM policy you entered in step 11 in the text box, and press **Enter**.

    ![Search and select created policy](https://docs.soracom.io/_astro/find-policy.DmMafUiH_ZCJKSg.webp)

    The AWS IAM policy you created will be displayed.

14. Check the boxes for the AWS IAM policy you created and click **Next**.

15. Enter a name for the IAM role in **Role name** and click **Create role**.

16. Click on the name of the IAM role you created. You should see its ARN which looks like `arn:aws:iam::900012345678:role/beam-tracker-role`. Make a note of this **IAM Role ARN**, as we will use it later.

    ![IAM role ARN information](https://docs.soracom.io/_astro/note-arn.UzLqV87J_wv9iF.webp)

---

### 4. Register the IAM Role Credentials to Your Soracom Account

In order for Soracom Beam to have permission to send data to your Amazon Location Service Tracker, it needs to use the IAM role that we just created. Let's register the IAM role to your Soracom account by creading a new Soracom Credential Set. You will need the **IAM Role ARN** and **External ID** created earlier.

To create a credential set:

17. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. Click your **account menu**, then select **Security**.

    ![Security](https://docs.soracom.io/_astro/security.BCx3IafY_nrl5n.webp)

18. From the **Security** screen, click the **Credentials** tab. Then click the **Register credentials** button.

    ![Credentials](https://docs.soracom.io/_astro/credentials-set.DK57KL3Z_2sKzud.webp)

19. Enter your IAM credentials as follows, then click **Register**:

    ![Register credentials](https://docs.soracom.io/_astro/register-credentials.CyBEEfji_1V10Kq.webp)

    - **Credential Set ID**: Enter a name to identify the credential. Example: `AWS-IAM-role-credentials-tracker`.

    - **Type**: Select `AWS IAM Role credentials`.

    - **Role ARN**: Enter your **IAM Role ARN** from earlier, such as: `arn:aws:iam::900012345678:role/beam-tracker-role`.

    - **External ID**: Enter your **External ID**. Example: `External-ID-abcdefgh12345678`.

## Configure Soracom Beam

### 5. Create a Group

1. From the **☰ Menu**, open the **Groups** screen.

2. If this is your first group, click the **Create a group** button. If not, click the **+ Add Group** button.

3. Enter a descriptive name for your group such as `beam-tracker` and click **Create**.

4. From the **☰ Menu**, open the **SIM Management** screen.

5. From the list of subscribers, click the **☑** for the SIM you want to modify.

6. Click the **Actions ▾** menu, then select **Change group**.

7. From the **Group** dropdown menu select the group we have just created, then click **Change Group**.

---

### 6. Set up Soracom Beam

Configure Beam's Website entry point. If configured as described here, the following functions are possible:

- Transfering data sent from devices using Soracom IoT SIM cards from Beam to your Tracker.
- Retrieving data stored in your Tracker from devices using a Soracom IoT SIM.

> [!WARNING]
>
> Only the operations for changing group settings are explained here. For more information on how Groups work and what to do to create a group, see [Group Settings](https://docs.soracom.io/en/services/groups/settings).

8. From the **☰ Menu**, open the **Groups** screen.

9. Select the group that we created in the previous step (e.g. `beam-tracker`).

10. Click **SORACOM Beam** on the SIM group screen.

11. Click **+ Add Configuration** → **Website Entry Point**. The **SORACOM Beam - Website configuration** screen will be displayed.

12. Configure the following fields:

    ![Website Configuration](https://docs.soracom.io/_astro/website-configuration.BYDKajW7_2rxlIi.webp) ![Authorization Header](https://docs.soracom.io/_astro/authorization-header.DiGe8AMt_Z2ekt3a.webp)

    - **Configuration Name**: Enter a name for the configuration. Example: `Amazon Location Service Tracker`.

    - **Destination** → **Protocol**: Select `HTTPS`.

    - **Destination** → **Host Name**: Enter `tracking.geo.${Amazon Location Service region}.amazonaws.com`. Example: `tracking.geo.us-east-1.amazonaws.com`.

    - **Destination** → **Port Number**: Leave blank.

    - **Header Manipluations** → **Authorization Header**: Turn it on and set it as follows:

      - **Type**: Select `AWS Signature V4`.
      - **Service**: Select `geo` (Amazon Location Service).
      - **Region**: Select the Amazon Location Service region.
      - **Credential ID**: Select the AWS IAM role credentials you registered in the Register AWS IAM Role Credentials step (e.g. `AWS-IAM-role-credentials-tracker`).

13. Click **Save**.

In case your SIM has not been added to the group with this Beam configuration, make sure to [add your SIM](https://docs.soracom.io/en/services/groups/usage#managing-devices) so that Beam will transmit the data to Amazon Location Service.

---

### 7. Enable Soracom Air Metadata Service

In the steps that follow, we will use the Soracom Air Metadata Service to obtain the SIM ID and use it as a device identifier in Amazon Location Service. Therefore, activate the Metadata Service in the group to which the SIM being used belongs. For more information, see [Configuring Metadata Services](https://docs.soracom.io/en/services/air/metadata-service#configuration).

14. From the **Basic Settings** tab, click the **SORACOM Air for Cellular** panel to expand its settings.

15. Enable the **Metadata Service** option by switching the option to **ON**.

16. Disable **Readonly** and Enable **Minimize Response Body**

    ![Metadata Service](https://docs.soracom.io/_astro/metadata-service.BKRPYxPm_1epu22.webp)

17. Click the **Save** button at the bottom of the panel.

## Test the Connection

In this step we will create a tracker named `beam-tracker` using a Python script in your Tracker.

### Create a Tracker

1. Install the `requests` package on the device.

   ```bash
   pip install requests
   ```

2. Download **[create\_tracker.py](https://users.soracom.io/ja-jp/docs/beam/aws-location-service/files/create_tracker.py)** to the device.

   > [!WARNING]
   >
   > **create\_tracker.py** is a sample script that uses Metadata Service to obtain the SIM ID and create a new tracker named `beam-tracker` in your Tracker.

3. Create a tracker by executing the following command on the device:

   ```bash
   python create_tracker.py
   ```

   The console will then ouput information about your tracker:

   ```
   8942300000012345678
   {'TrackerName': 'beam-tracker', 'TrackerArn': 'arn:aws:geo:us-east-1:900012345678:tracker/beam-tracker', 'CreateTime': '2023-01-11T12:20:04.118Z'}
   ```

---

### Send Location Data to the Tracker

1. Download **[send\_locations.py](https://users.soracom.io/ja-jp/docs/beam/aws-location-service/files/send_locations.py)** to the device.

   > [!WARNING]
   >
   > **send\_locations.py** is a sample script that uses the Metadata Service to obtain the SIM ID and send three fixed locations at 2 second intervals to a tracker named `beam-tracker` in your Tracker.

2. Execute the following command on the device to send the location information:

   ```bash
   python send_locations.py
   ```

---

### Retrieve Location Data from the Tracker

If your application requires your device to retrieve past location data, you can do so with the following example. However if not, you can skip this section.

1. Download **[get\_locations.py](https://users.soracom.io/ja-jp/docs/beam/aws-location-service/files/get_locations.py)** to the device.

   > [!WARNING]
   >
   > **get\_locations.py** is a sample script that uses the Metadata Service to retrieve the SIM ID and get location information for the past 3 days from a tracker named `beam-tracker` in your Tracker.

2. Execute the following commands on the device to obtain location information:

   ```bash
   python get_locations.py
   ```

   The console will then output information about the retrieved location data:

   ```
   {'DevicePositions': [{'DeviceId': 'beam-tracker-8942300000012345678', 'SampleTime': '2023-01-19T09:50:09.933Z', 'ReceivedTime': '2023-01-19T09:50:13.177Z', 'Position': [139.7583, 35.6664], 'Accuracy': {'Horizontal': 1}}, {'DeviceId': 'beam-tracker-8942300000012345678', 'SampleTime': '2023-01-19T09:50:15.951Z', 'ReceivedTime': '2023-01-19T09:50:16.522Z', 'Position': [139.7501, 35.6701], 'Accuracy': {'Horizontal': 1}}, {'DeviceId': 'beam-tracker-8942300000012345678', 'SampleTime': '2023-01-19T09:50:18.733Z', 'ReceivedTime': '2023-01-19T09:50:19.3Z', 'Position': [139.744207, 35.669823], 'Accuracy': {'Horizontal': 1}}]}
   ```