Cordial Setup¶
To use Cordial, you’ll need an Amazon Web Services account and a computer with Docker. These instructions will walk you through setting both of these up and testing that Cordial is setup correctly.
We run Cordial in a Docker container to make setup easier. On Ubuntu, you’ll be able to work inside of the Docker container with an IDE and other visualization tools, without setting them up on your computer. When you use the run script, your work in catkin_ws
and scratch
will be saved even if you close the container, because we are using Docker volumes. You can also pass files back and forth between the container and your computer while it’s running by putting them in the shared
directory in cordial/docker
.
Getting your Amazon Web Service credentials¶
For Cordial to speak we use Amazon Polly, which requires an Amazon Web Services account. At our current usage, using Amazon Polly is free up to a certain level), but you will need a credit card to create an account.
- Create an Amazon Web Services account.
- Once you sign in, in the top right of the page, click your account name (mine says “Audrow”), then in the drop-down menu click “My Security Credentials,” then click “Create New Access Key.”
- Record your access key and keep it somewhere safe. You can do this by downloading this or just viewing it and copy-pasting it to somewhere for later reference.
Note
It is best practice to create separate accounts with less access than your root account and use those access keys, see Amazon’s security best practices.
Running Cordial in a Docker Container¶
Setup Docker:
Install Docker:
curl -fsSL https://get.docker.com -o get-docker.sh sh get-docker.sh
Set Docker to run without
sudo
:sudo groupadd docker sudo gpasswd -a $USER docker newgrp docker
Test that Docker is installed correctly and works without
sudo
:docker run hello-world
Setup Docker-compose:
Install Docker-compose:
sudo curl -L "https://github.com/docker/compose/releases/download/1.25.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose
Check that Docker-compose is installed correctly:
docker-compose version
Run Cordial’s Docker container. The first time it will take a while, say 10 minutes, depending on your computer and internet speed:
git clone https://github.com/robotpt/cordial bash cordial/docker/run.sh
Note
You can pass arguments to the run script to change how the program is run. If you do
bash cordial/docker/run.sh terminal
, the Docker container will run in your current terminal. This is possibly the only way to run Cordial on a Windows or Mac computer without using a virtual machine.Once in the Docker container, configure your AWS credentials by typing
aws configure
in the terminal that pops up. You will be prompted to enter the following:- For
AWS Access Key ID
andAWS Secret Access Key
, enter the corresponding credentials associated with your AWS account. - For
Default region name
, enter the code the region code that you’d like to use. In Los Angeles, we typically useus-west-1
. You can find a full list of region names here. - For
Default output format
, enterjson
.
- For
Test that everything is setup correctly by running an example in the Docker container, for example:
roslaunch cordial_manager example_say_and_ask_on_gui.launch
You can then open a web-browser and go to
localhost:8080
for the face andlocalhost:8081
for the GUI. Once these are open, an interaction should begin. You should see the face moving, see the text and some options on the GUI, and hear the voice speaking.Troubleshooting:
- If nothing happens, check the terminal where you ran the above command. It is quite likely that something is wrong with the AWS credentials. Go back to the previous step.
- If the face moves and GUI displays but you hear no voice, it’s possible Docker can’t find your sound card or that some other program is occupying your sound card. Try closing anything that might play sound (such as a Google Meet call) and retry. You might also see if you can play any sounds from the Docker container, by running, for example,
beep
.