The AWS DeepRacer Event Manager (DREM) is used to run and manage all aspects of in-person events for AWS DeepRacer, an autonomous 1/18th scale race car designed to test reinforcement learning (RL) models by racing on a physical track.

DREM offers event organizers tools for managing users, models, cars and fleets, events, as well as time recording and leaderboards. Race participants also use DREM to upload their RL models.

Note: DREM is designed for use with AWS DeepRacer cars running firmware version 20.04 and above. Earlier firmware versions are not supported. If you need to update your device, see Update and restore your AWS DeepRacer device

The deployment requires the following tools:

• Docker with ARM build support
• AWS CLI *
• AWS CDK with Typescript support (Tested with 2.6.0) *
• Node.js version 18.x *
• (Optional) Make buildtool. We provide a Makefile with all required targets for easy use. We recommend installing Make. *

* Included if you use docker compose

The deployment is currently supported in theses regions:

US East (N. Virginia)
US East (Ohio)
US West (Oregon)
Europe (Frankfurt)
Europe (Stockholm)
Europe (Ireland)
Europe (London)
Asia Pacific (Tokyo)
Asia Pacific (Singapore)
Asia Pacific (Sydney)

Please note: It takes approximately an hour for all of the DREM resources to be deployed.

1. Setup environment
2. Create a GitHub personal access token
3. Store Token in Secrets Manager
4. Install build dependencies
5. Create required build.config (if using Make)
6. Bootstrap AWS CDK
7. Install DREM
8. Accessing DREM
9. Setup Amazon Cognito to use Amazon SES for email sending (optional)

If you are deploying DREM for use to support your AWS DeepRacer event(s)

In your terminal of command line, enter the following commands:

# Region where you wish to deploy
export REGION=<your-region>
# Your e-mail
export EMAIL=<your-email>
# Version to deploy, release/stable is the default, but you can pin to a version e.g. release/2.6
# Release list is available https://github.com/aws-solutions-library-samples/guidance-for-aws-deepracer-event-management/releases
export SOURCE_BRANCH=release/stable
# If you are not using the default label 'main', change this to match your environment
export LABEL=main

# Setting variables we can do programmatically.
export ACCOUNT=$(aws sts get-caller-identity --query Account --output text)

# Optional (if you have AWS CLI configured with you credentials already)
export AWS_ACCESS_KEY_ID=<key>
export AWS_SECRET_ACCESS_KEY=<secret>
export AWS_SESSION_TOKEN=<token>

Follow the instructions on GitHub Docs to create a personal access token (Classic).

When creating the token select public_repo for the selected scope.

Store the personal access token in Secrets Manager.

1. In the AWS Management Console, navigate to Secrets Manager
2. Click Store a new secret
3. On the Choose secret type step select Other type of secret
4. Select the Plaintext tab
5. Completely remove the example text and paste your secret with no formatting no leading or trailing spaces
6. Select the aws/secretsmanager encryption key
7. Click Next
8. On the Configure secret step set the Secret name to drem/github-token
9. On the Configure rotation step click Next
10. On the Review step click Store

npm install

Note. This step is only required if Make is used for the later steps.

Build your build.config file

echo "region=$REGION" >> build.config
echo "email=$EMAIL" >> build.config
echo "account_id=$ACCOUNT" >> build.config
echo "label=$LABEL" >> build.config
echo "source_branch=$SOURCE_BRANCH" >> build.config

In this step, you bootstrap the CDK. Two options are listed below.

make bootstrap

cdk bootstrap -c email=$EMAIL -c account=$ACCOUNT -c region=$REGION -c source_branch=$SOURCE_BRANCH -c label=$LABEL

This command creates a CodePipeline pipeline, this pipeline coordinates the build and deployment of all required DREM services.

make install

The deployment of DREM through the pipeline will take approximately 1 hour. You can monitor the progress of the deployment by accessing the AWS Account you are deploying DREM into and going into AWS CodePipeline and reviewing the pipeline. As part of the deployment, the email address provided will become the admin user for DREM. An email with temporary credentials to access DREM as well as the a link will be sent to the email address provided. Note: The link won't work until the codepipeline has fully finished. When logging in for first time, the username is admin and the user will be prompted to change the temporary password.

In the default configuration Amazon Cognito only supports 50 signups a day due to a hard limit on the number of signup emails it is allowed to send. To resolve this you must enable the integration with Amazon SES.

To manually enable this integration, you can follow these steps:

1. Purchase/Register your domain in Route 53
   • you can use other DNS providers but those steps are not detailed here
2. Add the domain to the verified identities in Amazon SES
3. Take the SES account out of sandbox mode
4. Navigate to your Amazon Cognito User Pool
5. Click Edit in Messaging, Email
6. Switch the configuration to Send email with Amazon SES and complete the rest of the email configuration appropriately
7. Click Save changes

Complete all steps in Option 1. Deploy DREM for use at an event

Make sure you have a GitHub account setup, then make a fork of the DREM repo. Forking can be done by logging into GitHub and then clicking "Fork" on the top right of the DREM repo home page.

Check the git URL for your local repo

git remote get-url origin

Switch the repo to your fork

git remote set-url origin <your-github-username>/guidance-for-aws-deepracer-event-management

Edit the build.config you created earlier add the following line, substituting the name of your repo:

source_repo=<your-github-username>/guidance-for-aws-deepracer-event-management

and edit the source_branch to match a branch in your fork, probably main to start with

source_branch=main

This command deploys the updated CodePipeline pipeline, pointing at your new fork and branch.

make install

As per the deployment prerequisites with the following additional tools

• GIT
• Visual Studio Code
• Python3

A number of plugins are recommended when contributing code to DREM. VSCode will prompt you to install these plugins when you open the source code for the first time.

We recommend that you use the Makefile based commands to simplify the steps required when developing code for DREM.

If you plan to help develop DREM and contribute code, the initial deployment of DREM is the same as above. Once DREM has deployed, to make the deployed DREM stack available for local development, run the following commands, alternatively the stack can be run using docker compose to create containers for each of the three react applications that make up DREM:

Running all resources and installing all dependencies on the local machine

make local.install

Note: You will need to have your local development environment setup/authenticated with AWS

make local.config

To run the main DREM application

make local.run

To run the DREM leaderboard application

make local.run-leaderboard

To run the DREM streaming overlays

make local.run-overlays

Using docker compose to build and run containers for each of the react applications that make up DREM.

Note: You will need to have your local development environment setup/authenticated with AWS

make local.config.docker

With docker running on your machine, use the following commands to build and start the containers. Builds the containers if they aren't already built and runs them in 'detached' mode

docker compose up -d

To access the logs as the containers are running

docker compose logs -f

To stop the containers

docker compose down

To rebuild a container

docker compose build --no-cache <container name>

To restart a container

docker compose restart <container name>

To run a command in a new container instance

docker compose run <container name> /bin/sh

To execute a command in a running container

docker compose run <container name> <command>

To deploy changes to your backend (Cognito, Lambda, DynamoDB, etc.), make the updates to CDK and then commit the changes to your fork and branch that you have pointed the pipeline at and the pipeline will automatically detect and deploy the changes.

When you have finished using DREM for your event, the application can be removed using either Makefile based commands or manually.

make clean

npx cdk destroy -c email=$EMAIL -c account=$ACCOUNT -c region=$REGION -c branch=$BRANCH

make drem.clean-infrastructure

aws cloudformation delete-stack --stack-name drem-backend-$BRANCH-infrastructure --REGION $REGION

Not all of the elements from the stack are able to be deleted in an automated manner and so once the initial attempt at deleting the stack has failed with DELETE_FAILED status you need to manually delete the stack using the console and retain the resources that can't be automatically delete. Once the stack has been deleted the retained resources can be manually deleted

ModelsManagerClamScanVirusDefsBucketPolicy*

(Known issue - we are looking to resolve this with an updated version of how we use ClamScanAV within DREM)

make drem.clean-base

aws cloudformation delete-stack --stack-name drem-backend-<branch-name>-base

Not all of the elements from the stack are able to be deleted in an automated manner and so once the initial attempt at deleting the stack has failed with DELETE_FAILED status you need to manually delete the stack using the console and retain the resources that can't be automatically delete. Once the stack has been deleted the retained resources can be manually deleted

logsBucket*

Using the console remove the S3 bucket created in step 1 of deploying DREM.

aws ssm delete-parameter --name /drem/S3RepoBucket --region $REGION

## Sample models

DREM has sample models trained used the reward functions in the AWS DeepRacer console that are available to load on to cars at events.

• AtoZ Speedway clockwise
  • AtoZ-CW-Centerline-tracking.tar.gz
  • AtoZ-CW-Steering-penalty.tar.gz
  • AtoZ-CW-Throttle-penalty.tar.gz
• AtoZ Speedway counter clockwise
  • AtoZ-CCW-Centerline-tracking.tar.gz
  • AtoZ-CCW-Steering-penalty.tar.gz
  • AtoZ-CCW-Throttle-penalty.tar.gz

They were trained for 12 hours using the PPO training algorithm, default discrete action space and the Hyperparameters:

• Gradient descent batch size: 64
• Number of epochs: 10
• Learning rate: 0.0003
• Entropy: 0.01
• Discount factor: 0.95
• Loss type: Huber
• Number of experience episodes between each policy-updating iteration: 20

These models can be found in lib/default_models

See CONTRIBUTING for more information.

This library is licensed under the MIT-0 License. See the LICENSE file.