Waterloo Steel:Platform Setup Workstation

0. Common

0.1 Remote & Collaboration

0.1.a AnyDesk : remote screen & remote VPN ssh

For details, see in https://anydesk.com/en

0.1.b NoMachine : Local Network Remote Screen

We use this tool to access Jetson Orin without monitor with GUI
Best for local network
minimal computer resources needed

0.1.c TeamViewers : remote screen only

Basic, but recommend AnyDesk over TeamViewers

0.1.d Remote Desktop : remote screen

Worst in terms of performance
high cost on computer resources
Best for windows???

1. Ubuntu

[@jack.xu@uwaterloo.ca]

1.1 Install Ubuntu

1.1.1 Bootable USB

search for bootable USB

1.2 Ubuntu Initial Setup

1.2.1 Basic Tools:

1.2.1.a) Net-tools:

$ sudo apt install net-tools
# now you can check ip:
$ ifconfig

1.2.1.b) Open-SSH

$ sudo apt update
$ sudo apt install openssh-server
# allow bypass firewall
$ sudo ufw allow ssh 
# check ssh status:
$ sudo systemctl status ssh

to connect to this server:

$ ssh username@ip_address
# search for local network ip in case
$ ip a

1.2.1.c)* (Optional) NoMachine (see more in Platform-Setup-Hardware):

NO Machine: https://downloads.nomachine.com
- Please check your OS version via:
```
$ arch
```
📣 You will see all available local NoMachine through the APP, and allow us to remote screen from Mac, WIN, Ipad, and Ubuntu.

1.2.2.d)* (optional) Remote Desktop Auto-Sleep and Auto-Wake Scheduling:

Please see detailed guide in [Waterloo-Steel/Platform-Hardware-Setup.md]

1.2.2 Optional Advanced Tools:

1.2.2.a) Zenith

$ sudo apt install curl
$ curl -sL https://raw.githubusercontent.com/wimpysworld/deb-get/main/deb-get | sudo -E bash -s install deb-get
# then install:
$ deb-get install zenith
$ deb-get update
$ deb-get upgrade

1.2.x Note:

📓 Now you may access Ubuntu remotely, and setup following locally on Ubuntu or remotely

1.3 Ubuntu Workspace Setup:

1.3.0 (Desktop) Share Wifi Through Ethernet:

This is the preferred environment. PCW computers will be using Ubuntu 20.04. Reference
1. Open your Settings > Network.
2. Under the Wired section, click the plus sign to create a new settings profile. Name the profile "Shared" or whatever you want.
3. In the IPv4 tab, choose "Shared to other computers". Click Apply. Your computer should now be networked with the AP. 10.42.0.0/24 is the default subnet used by Ubuntu for this setup, but there's not necessarily a guarantee that your computer will use that subnet. If the next step returns no results, run ip address or ifconfig and look for the IP of your Ethernet interface (usually eth0) there.

1.3.1 ZSH and oh-my-zsh

install zsh first

$ sudo apt install zsh
# change to default in zsh
$ sudo chsh -s $(which zsh)
$ sudo chsh -s $(which zsh) $USER

Oh-my-zsh (THE hipster dev tool + coke)

$ sudo apt install curl
$ sudo apt install git
$ sudo apt install vim
$ sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# to modify themes:
$ sudo vim ~/.zshrc
## Recommended themes: `ys` and `jonathan`
$ source ~/.zshrc

ℹ️ https://github.com/ohmyzsh/ohmyzsh

ℹ️ Themes: https://github.com/ohmyzsh/ohmyzsh/wiki/Themes

1.3.2 TMUX: virtual terminal within terminal

https://linuxize.com/post/getting-started-with-tmux/
Pretty/Easy-to-use Custom Mod: https://www.hamvocke.com/blog/a-guide-to-customizing-your-tmux-conf/ (except ctrl-b mod)
```
$ sudo apt install tmux
```

📓 Do not use multiple ssh clients, as they will make the system a bit heavier.

🔥 Tmux can still run in the background, even if the computer is disconnected from the internet.

⚠️ Normal ssh sessions without tmux will terminate the program if your ssh client is disconnected

1.3.2 VIM:

set github editor to vim:
```
$ git config --global core.editor "vim"
```
or have env variable in zshrc: export GIT_EDITOR=vim
Why VIM? ---> personal preference

1.3.3 SSH Keys & Github

generate key

$ ssh-keygen -t ed25519 -C "your_email@example.com"

copy the public key
```
$ cat ~/.ssh/id_ed25519.pub
```
paste to github SSH keys under personal account profile

1.3.4 VSCode Remote SSH:

🎫 I often use VSCode Remote SSH to modify codebase --Jack

Open VSCode, and make sure [Remote-SSH] is installed in EXTENSIONS: MARKETPLACE on left tab
[CMD + P] to open command pallette , and type command "> SSH" and select [Remote SSH: Connect to Host ...]
Enter host username and ip:
```
$ ssh username@ip_address
```
Now you can open folder in local VSCode editor and modify the remote files
:happy:

1.4 [:star:] UWARL ROS Catkin Workspace Setup

Install Catkin Workspace + Hardware Setup + ROS in one script

🔥 (hot-takes) on [Hardware v2] : A unified multi-platform configuration

UWARL_catkin_ws/src: A single common catkin workspace that can be deployed dynamically across multiple platforms. This repository will track other ROS components as submodules on particular commit hask token (without tracking physical files and changes).

uwarl-robot_configs: An all-star installation toolkit that will configure any hardware automatically with simple bash scripts.

Supported OS: Ubuntu 18.04 and Ubuntu 20.04 (includes auto-install for ROS-Noetic)

🚨 Pre-req:
1. **Make sure SSH authenticated with Github, see instruction @ **
2. ZSH as default Shell

1.4.1 Clone configurations:

$ cd ~ && git clone git@github.com:UW-Advanced-Robotics-Lab/uwarl-robot_configs.git

1.4.2 Select Configuration Branch:

$ cd ~/uwarl-robot_configs
# check all available branches:
$ git branch -a
# EX: select `universal/ros1/data-analysis/session-feb-2023`:
$ git checkout universal/ros1/data-analysis/session-feb-2023

1.4.3 🌶️ Register your PC in `common.h`:

$ vim ~/uwarl-robot_configs/scripts/common.sh

Define Package Dependency:

⚠️ Please add submodules iff you needed them to reduce overall build_ws compile time for different workstation with different purposes.

📓 These will tell the script everytime you call update_ws what submodules to download from, else it will just be an empty folder under UWARL_catkin_ws/src without any contents.

# $USER = "oem":
SUBMODULES_FOR_JX_OEM=(
    ## SUMMIT Side:
    "multimap_server_msgs"
    "system_monitor"
    "uwarl-multimap_server"
    "uwarl-robot_localization_utils"
    # "uwarl-robotnik_base_hw"  # not needed for simulation !  # [x86_64 only]
    "uwarl-robotnik_msgs"
    "uwarl-robotnik_sensors"
    # "uwarl-summit_xl_common"
    "uwarl-summit_xl_robot"
    "waterloo_steel"
    ## WAM Side:
    "uwarl-barrett_wam_hw"      # : Enabled for local dev.  # [x86_64, aarch64/arm64]
    "uwarl-barrett_wam_msgs"
    "uwarl-realsense_ros"       # [L515 Support]
)

In function source_ros() , register PC as below:

If Out of network, apply registration and edit below as needed:

Find you user name by entering in terminal: > echo $USER

    elif [[ $USER = "jx" ]]; then
        # manual config:
        export UWARL_ROBOT_PC_NAME="JX_DESKTOP_JACK"
        export ROS_DISTRO=noetic
        export DISPLAY=$DISPLAY_DEFAULT
        export PYTHONPATH_ROS=/usr/bin/python3
        export PYTHONPATH=$PYTHONPATH_ROS
        # welcome:
        ic_wrn " - NON-Robot PC User [$UWARL_ROBOT_PC_NAME] detected!"
        # ros core:
        sync_ros_core_if_in_robot_network_else_localhost $ROS_IN_NETWORK_EXTERNAL_PC_IP_BLOCKED 
        
    ### TEMPLATE:
    # elif [[ $USER = "{$USER}" ]]; then
    #     export UWARL_ROBOT_PC_NAME="{ENTER HERE}"
    #     # manual config:
    #     export ROS_DISTRO=noetic
    #     export DISPLAY=$DISPLAY_DEFAULT
    #     export PYTHONPATH_ROS=/usr/bin/python3
    #     export PYTHONPATH=$PYTHONPATH_ROS
    #     # welcome:
    #     ic_wrn " - NON-Robot PC User [$UWARL_ROBOT_PC_NAME] detected!"
    #     # ros core:
    #     sync_ros_core_if_in_robot_network_else_localhost $ROS_IN_NETWORK_EXTERNAL_PC_IP_BLOCKED

[OPTIONAL] to better switch the ros log level: (new feature, added Sept 29, 2023)
1. You may copy the default config:
```
$ cp $UWARL_CONFIGS/scripts/configs/uwarl-rosconsole.config $UWARL_CONFIGS/scripts/configs/uwarl-rosconsole_{user}.config
```
2. Add this config to your PC registration:
```
        # console config:
        export ROSCONSOLE_CONFIG_FILE=$UWARL_CONFIGS/scripts/configs/uwarl-rosconsole.config # debug level
```
3. Every time, you change this config file, the roscore console will output different level of logging messages
4. For additional details, please refer to http://library.isr.ist.utl.pt/docs/roswiki/rosconsole.html

[OPTIONAL] If you also plan to use as In-network PC as well, where the PC IP is binded to a specific IP in the robot network, and connected to UWARL_171102A_5G

Define New PC and Network Parameters:

### [ Robot Network: UWARL-171102A_5G Wifi ] ###
...
# - Known PC IP:
export ROS_JX_IN_NETWORK_PARALLEL_PC_IP=192.168.1.100
# - Unknown PC IP, to register into the robot network:
#   - Once you connect to the robot network, and `$ ifconfig | grep 192.168.1` to check your IP
#   - Uncomment, and apply the IP
#   - Move to the Known PC IP section, once you have confirmed your IP.
#   - And replace the ROS_IN_NETWORK_EXTERNAL_PC_IP_BLOCKED with your IP:
# export ROS_AJ_IN_NETWORK_DESKTOP_PC_IP=192.168.1.x
# export ROS_P51_IN_NETWORK_LENOVO_PC_IP=192.168.1.x
# export ROS_JX_IN_NETWORK_OEM_PC_IP=192.168.1.x
# export ROS_P50s_IN_NETWORK_LENOVO_PC_IP=192.168.1.x

1.4.4 🌶️ Register PC Submodules Mapping in `auto-config_UWARL_catkin_ws.zsh`

add attributes as below after line 80
[Optional]:
- You may uncomment install_misc_utilities # misc apt
  - to install some apt packages (tree, tmux, git, zsh, vim)
- You may uncomment install_librealsense_if_not
  - to install driver for librealsense cameras
- You may install PCAN by adding:
  - NETDEV: install_pcan_if_not NETDEV_SUPPORT
  - NON_NETDEV: install_pcan_if_not NETDEV_SUPPORT
- You may install Dlink Dongle for wifi dongle provided in the lab:
  - install_dlink_dongle
- You may add install_libbarrett_if_not for wam_node hardware dependency

    "JX_DESKTOP_JACK")
        load_submodules "${SUBMODULES_FOR_JX_DESKTOP[@]}"
        install_misc_utilities # misc apt 
        install_libbarrett_if_not
        install_librealsense_if_not # for Intel Sensors
    ;;

1.4.5 Install the repo and configure hardware with auto-script:

$ cd ~ && ./uwarl-robot_configs/scripts/auto-config_UWARL_catkin_ws.zsh

📓 this script will install automatically based on the user name (e.g. uwarl-orin) to identify the PC space

🔥 This will install ROS Noetic for you, if you have ubuntu 20.04 focal (like Jetson) , otherwise, you have to install manually OR add a script to it as well?

1.4.6 *Reboot is Required if it is the first time installing libbarrett !!

1.4.7 Catkin Build:

# source robot config env & ros
$ source ~/.zshrc
# build:
$ build_ws # from anywhere, which will does the job for you :P (Jack is too lazy)
# source:
$ source_ws # lemme know if we should auto-source after build, :wink:

1.4.8 Commit Config settings:

$ cd_config
$ git status
$ git commit -a
# push to remote:
$ git push

1.5 How to use Configuration Toolchain:

1.5.1 Modifications:

switch workspace : git checkout {branch-name}
add modules: $ git submodule add {git-repo}
remove submodules: $ git submodule deinit {git-repo} and you may need delete the submodules in .gitmodules file
Create a new branch of workspace: git checkout -b waterloo_steel/adlink-mxe211-melodic/{node}/{feature}

1.5.2 Commit and Push:

Commit all changes under submodules
Make sure you run this: $ ./git-status-all.sh to log all status into git-status-all.log
commit all current workspace changes: $ git add . && git commit -a
Push workspace $ git push or upload a branch $ git push -u {your-branch-name}

1.5.3 Pull latest repo:

$ cd_ws/src && git status # make sure no local changes
$ update_ws

1.5.4 Restart over the catkin workspace:

# delete current workspace
$ cd $HOME
$ rm -rf UWARL_catkin_ws 
# reinstall everything and build:
$ cd_config
$ ./scripts/auto-config_UWARL_catkin_ws.zsh
$ build_ws
$ source_ws

1.5.5 Shortcuts:

🌶️ Fore up-to-date shortcuts, you may find in the > uwarl-robot_config/README.md <

# update (pull recursively in a batch) of the entire workspace with all required submodules (as noted in common.sh) from anywhere
$ update_ws
# build ws from anywhere
$ build_ws
# source ws from anywhere
$ src_ws
# source ~/.zshrc from anywhere
$ src_zsh
# cd into workspace from anywhere
$ cd_ws
# check wworkspace status from anywhere
$ check_ws_status
# cd into robot_configs from anywhere
$ cd_config

# auto-gen Table of Contents for a specific markdown file
$ md_toc README.md 
# auto-gen Table of Contents for a specific directory containing all markdown files
$ md_toc_dir docs

1.x Tips

1.x.1 Commonly used command:

$ uname -r: OS check
$ cat /prov/version_signature: identify kernel
$ arp -a : Scan Local Network Devices and IPs
$ tree -L 1: list hierarchy of directory in depth=1

1.x.2 Manually backup a directory of files:

EX: backup home directory [cite:how-to-backup]

sudo rsync -a --info=progress2 --exclude="lost+found" --exclude=".cache" /home/ /mnt/usbdrive/

2. Mac

[TODO]

3. Windows