Setting Up the Operating System

Windows

Install Ubuntu 24.04 using WSL.

Mac

Install and open Multipass and launch Ubuntu 24.04 LTS.
Navigate to ‘All Instances’ and stop username-hostname.
Click on username-hostname in ‘Name’ column. Switch from ‘Shells’ to ‘Details’ at the top.
Click ‘Configure’ under ‘Resources’. Multipass's default settings will not support the simulator. Change CPUs to 4+, Memory to 4+, Disk to 10+ (at a minimum).
Navigate back to ‘All Instances’ and start username-hostname.
'Open shell' option in Multipass will not work on Mac. Instead, open a Terminal and run the following command to launch Multipass.
multipass shell username-hostname

Linux

The JaiaBot project supports Ubuntu 24.04.

Preparing the Workspace

Clone the JaiaBot repository. Install git if needed.
sudo apt install git

````

git clone https://github.com/jaiarobotics/jaiabot ````
Run the setup scripts.
cd jaiabot/scripts

./setup-tools-build.sh

./setup-tools-runtime.sh
Move back to the JaiaBot repository. Run the build script.
cd ..

./build.sh

Launching the Simulator

Windows/Linux/Mac

Launch the JCC web interface.
cd src/web

./run.sh

Expected output:
WARNING:root:🏓 Pinging server localhost:40000
Launch the simulator in a separate terminal.
cd jaiabot/config/launch/simulation
Set the simulation to run 4 bots at a time warp of 5.
./generate_all_launch.sh 4 5

./all.launch

Expected output:
[all] 08:48:16: All processes running
Open Chrome and go to this address for the JCC:
- Windows/Linux
  
  http://localhost:40001/
- Mac - Open Multipass and find your Private IP address associated with the Ubuntu environment.
  
  http://XXX.XXX.XX.X:40001/

Stopping the Simulator

In any terminals that are running the web and simulator, type CTRL+C.

Troubleshooting the Simulator

To kill all processes, cd into jaiabot/scripts, run the kill command, and relaunch the simulator.
./kill-jaiabot-processes.sh
To refresh the build directory, cd into jaiabot and remove the build directory.
rm -rf build

Then recreate the build directory.
./build.sh
Verify you are using Python 3.12.

If you are getting an error when using our suggested cd path, you are most likely not in the right directory. Your current location will show following your username-hostname. For example, you are in the jaiabot scripts directory when you see:

ubuntu@username-hostname:~/jaiabot/scripts$

To see which directories you can move into, use ls. To go back a directory, use cd ... You want to move to the directory with your cloned jaia repository. We keep ours in our home directory, so if you want to follow our cd commands directly, this would be the best option.

Troubleshooting with MacBooks

Purge Multipass in terminal if there's no space on disk or memory.

Modifying Code

If you are modifying code on a Mac, create an SSH Key first.

Launch the simulator.
Modify the code as you see fit.
Shut down the simulator and JCC web interface. In any terminals that are running, type CTRL+C.
Build the code.
Repeat launching the simulator.
With the new code tested, it can be deployed to your Jaia System or submitted for review by creating a pull request.

Creating an SSH Key (MacBooks)

Make sure your Multipass instance is running.
Open one terminal and run the following command.
multipass shell username-hostname
Enter your home directory and SSH key.
cd ~/.ssh

ls

You should see an authorized_keys file.
Enter the authorized_key files.
nano authroized_keys
Switch to your local computer on another terminal window. Generate SSH key.
cd .ssh

ssh-keygen

You may have to hit enter multiple times to bypass passwords.
ls

You should see a key that is of the form id_edXXXXX and id_edXXXXX.pub. The following command should generate a key.
cat id_edXXXXX.pub
Copy and paste the output from the previous step into the nano file in the other terminal window.
- CTRL+o, enter, CTRL+x – saves and closes the nano tab.
Switch back to the other terminal (local computer terminal). Set up a config file.
nano config
Inside the config file enter this text. Then save and exit:
IdentityFile ~/.ssh/id_edXXXXX

Host jaia

HostName <IP address from multipass instance>

IdentityFile ~/.ssh/id_edXXXXX

User ubuntu
Enter the environment with your private IP address (XXX.XXX.XX.X).

ssh ubuntu@XXX.XXX.XX.X
If prompted, enter Yes (Y).
Logout of the environment.
Exit
Open your IDE (We reccomend VSCode) and download "Remote-SSH" Extension.
(Shift, Command+P) – This opens the search bar. Search "ssh." Select "Remote-SSH: Add New SSH Host..." and hit Enter.
Type "ssh ubuntu@XXX.XXX.XX.X" in search bar. Hit Enter.
Select /ssh/config. Hit Enter.
There should be a popup in the bottom right corner. Hit "Connect".
Your SSH should be set up! You only need to do this once.

Deploying Code

Modify the codebase.
Connect to a hub router.
- Select the SSID JAIA-HUB-WIFI-X from Wi-Fi list (X indicates fleet number).
Create Docker image.
cd ~/jaiabot/scripts

./docker-build-build-system.sh
Stop the jaiabot services for the system you are deploying to. Note: X indicates fleet number and Y indicates bot number plus 100 or hub number plus 10.
ssh -i /path/to/key jaia@10.23.X.Y

sudo systemctl stop jaiabot
Deploy the simulator.
cd ~/jaiabot/scripts

Deploy to the BOT
jaiabot_systemd_type=bot ./docker-arm64-build-and-deploy.sh jaia@10.23.X.Y

Note: X indicates fleet number and Y indicates bot number plus 100.

Deploy to the HUB
jaiabot_systemd_type=hub ./docker-arm64-build-and-deploy.sh jaia@10.23.X.Y

Note: X indicates fleet number and Y indicates hub number plus 10.
Start jaiabot services.
ssh -i /path/to/key jaia@10.23.X.Y

Note: X indicates fleet number and Y indicates bot number plus 100 or hub number plus 10
sudo systemctl start jaiabot

Note: (takes about 1 min to start)

Debugging

Make sure if you are upgrading that you do the entire fleet or stop the services on the systems you are not using.
This will limit any unexpected issues as mismatched dccl packets cannot be interpreted.
If you get errors during this upgrade process please contact your Jaia representative.

Table of Contents: