Development Environment Setup

This page covers the following topics:

• which software do you need to install in order to be able to develop software for pib?

• how to setup a backend that is suitable for development, given your current task at hand

• how to work with branches in the pib-rocks github repositories.

We will start with the basic setup and background knowledge that is required for anyone who plans on doing pib-related software-development and then dive deeper into topics related to setup for working on specific parts of the software (in paticular: frontend vs. backend). So let’s start with the very core software needed.

IDE (Visual Studio Code)

No matter which aspects of pib’s software you are planning to work on, the first thing you will need is an IDE where you can write your code. We recommend the use of Visual Studio Code (or VS-Code for short) You can find download-links for Windows/Linux/macOS here. The Windows section features an installer. For Linux, you can e.g. download a debian package and install it via apt. You can find detailed installation instructions for different operating systems by following one of these links: Windows, Linux, macOS.

VS-Code itself only comes with the very core features needed for software-development. To make full use of the IDE’s potential, you need to install extensions, which allow for additional features such as code-highlighting, editing code on remote machines and more. To install an extension, you need to first start VS-Code and then click the extension-icon on the left-sidebar:.

Open

A browser will open with a search-bar on top. You can simply enter the name of the extension you want to install and then click on the blue button of the respective result-entry.

Here is a small list of plugins, that we recommend for development on pib:

• Python (for ros/flask backend development)

• JavaScript (ES6) code snippets (for frontend/Angular development)

• Conventional Commits (for writing well-formed commit messages)

• Remote Development (for editing code on a remote machine)

• Docker (for working with Docker)

Version Control (Git)

Pib’s software is organized in multiple git-repositories, which are hosted on github within the pib-rocks organization. If you want to make changes in a repository, you first need to create a new branch, make some commits on that branch, push those commits and eventually (once you are done), create a pull-request on github, so that your changes will eventually be incorporated into the main-branch.

Before starting to work on your changes, the first thing you need to make sure is that you have git installed on your system. The easiest way to do this, is by running

if the command prints out some version number, then git is already installed on your system. If this is not the case, your next step is to install it. Detailed instructions on how to install git on Windows/macOS/Linux can be found here.

In this section, we will assume, that you have basic knowledge about the core functionality of git (commits, pushing, cloning, branching, …). If you seek more information about these core features, we refer to the official git documentation.

Now that you have successfully installed git on your system, the next thing you need to make sure it that you have a github-account and that this github account has the correct access-rights, to push changes to the remote repository etc. . Finally, you need to confirm that you have generated an ssh-key that is located on your system (and can be found by the ssh-agent), and that the public-key is uploaded to the github account which you want to use to make commits with. The ssh-key is used to authenticate yourself, while trying to access the remote repository on github. Detailed instructions on how to generate such a ssh-key can be found here. If you seek instructions on how to add the newly generated key to your github-account, you can look here.

Once git is installed on your local system, your github-account has the correct access-rights and a ssh-key is configured, you can now start to make changes to one of the repositories First clone the remote repository to your local machine via

In the following, we will discuss the topics of git-branch and github-pull-request management. If you are unfamiliar with these topics, you can find more information here:

• Git Branching

• GitHub Pull Requests

After you have created a local copy of the remote repository, you can now create a new feature-branch. Usually, a separate branch is created for each ticket and all changes related to that ticket, happen on this branch. The name of the branch matches the ticket number. Let’s say you want to work on ticket ‘PR-123: Implement cool feature', then you create a new branch called ‘PR-123’ (only the ticket number without the description). Feature branches should always be created from the ‘develop’ branch or (if you require features from another branch, which was not merged to ‘develop’ yet) from another feature branch. Do not create feature branches from main.

You now add changes by making commits to your feature branch. The commit messages should follow the Conventional Commits specification. The easiest way to ensure that this is achieved, is by using the Conventional Commits VS-Code extension (if you closely followed the setup instructions for VS-Code above, you should aready have it installed). With the extension installed and with VS-Code opened, type ‘Ctrl+Shift+P' to open the command palette and select 'Conventional Commits’. The extension now presents you multiple prompts and builds the commit message from your input:

1. "select the type of change that you're committing.": The plugin will provide you a list of types, from which you have to pick exactly one. Here is a short guide that will help you to select the correct type:

3. "select the scope of the change.": this should be the name of your branch, e.g.: “PR-123“.

4. "choose a gitmoji.": Select 'None'.

5. "write a short, imperative tense description of the change.": as the prompt indicates, you should briefly describe your changes in imperative tense. Assume that you have implemented the feature, that motor-settings are persisted to the database. Your description could in this case be something like “motor-settings are persisted to the database“.

6. "provide a longer description of the change.": You may provide a more detailed description of your change here. However, this can usually be omitted (by leaving the input blank).

7. "list any breaking changes or issues closed by this change.": Leave this input blank and continue.

The plugin will now have rendered a commit-message from your input and you can now click the blue 'commit'-button on the left in order to commit your changes.

Once you are done and you think your ticket is ready to be tested/reviewed, you create a new pull-request on github. The target-branch should generally be the branch from which you created your feature branch. If you created your feature branch from ‘develop’ the target branch is ‘develop’. If you created your feature branch from 'PR-555' the target-branch should be 'PR-555’. If you created your feature-branch from 'PR-555', but 'PR-555' was already merged to ‘develop’, the target-branch should be 'develop’. The name of your pull-request should adhere to the following pattern:

For example, if your pull-request's source-branch is 'PR-123' and the target-branch is ‘develop', the pull-request should be named 'PR-123 => develop'.

Now that we have discussed the basic-setup for doing software-development work on pib, let’s talk about the setup required for working on specific aspects of the software. Let’s begin with frontend-development.

Frontend Development (Cerebra)

Cerebra (pib’s frontend application) is developed using the Angular framework. In order to deploy the frontend during development, you first need to install the Angular CLI. Doing so requires, that Node.js is already installed on your system (preferably version 18.*). You can check if this is the case, by running following command:

If this command doesn’t print out some version number, it is not installed yet. For instructions on how to install Node.js, look here. After this is done, the Angular CLI can simply be installed via the following command:

The '-g' flag indicates, that Angular ClI will be installed globally and will not be limited to the scope of one specific npm-project.

The next step towards doing development work on Cerebra, is to clone the cerebra-repository to your local machine. This can be done by opening a terminal in your target folder and running

Moreover you need to update the submodules

You can now open the newly created 'cerebra'-folder in VS-Code and start making chages to the repository. Once you are done making changes, you probably want to deploy your code and see the results of your work. If you have never deployed your local copy of the frontend before, you first need to run the following command, which will install all npm-dependencies that cerebra requires:

Note, that this only has to be done once and that this step can be omitted all future times. Once you have installed cerebra’s dependencies, you can now deploy the application by running

Once the command outputs the line ‘Compiled successfully', you can open Cerebra, by navigating to 'http://localost:4200' in your browser of choice. You should now see the Cerebra-UI, however the application doesn’t bear all too much functionality yet, since you are probably not connected to a backend. You do not necessarily need to be connected to a backend, if you are only planning to do frontend-changes. In this scenario, you can connect to a mock-backend instead, which offers you a lot of the functionality, that a real backend would do. If you choose this approach, you can deploy Cerebra with the mock-backend with the following command:

You can now e.g. create new personalities or chats in the voice-assistant-component (which will be received by a mock-api and stored until you stop the execution of the command above), send messages in a chat and receive mock-responses, and so on. If you have a real backend running and want to connect to that backend instead, you first need to open the config-file that is located on the following path (relative to your project's root directory): ‘src/app/global-conf.json’. The file will look something like this:

Here you can simply change the value of the “ip“ field from “127.0.0.1“ to the ip-address of the machine, where your backend is running. Save the file and run ‘ng serve’ again. You should now be connected to your backend and should have a fully functional frontend application.

Now that we have discussed the setup needed for frontend development in detail, let’s go on and talk about the requirements for doing backend development.

Backend development

If you want to do development-work on the backend, the simplest way to do this is by running the setup-script by following the instructions on the bottom of the page here. The basic steps are the following:

• Make sure, you have a (physical or virtual) machine where Ubuntu 22.04.4 Desktop is installed, and you are logged in as user ‘pib' with password 'pib’ and that this user has root permissions

• follow the setup-instructions here

If this succeeds, you now have a fully functional backend, with all the required dependencies installed and where all the backend-components (ros-nodes, flask-api, …) are running. You can now simply start making changes to these components.

As mentioned before, there are two major options that you have for choosing an environment, where your backend should be running:

• a raspberry pi as part of a physical pib

• a virtual machine (or vm for short)

The first option is specifically of interest, if you plan to make changes to the backend components, that interact with hardware (i.e. pib’s motors or the camera). These changes cannot be tested by running the backend on a virtual machine, since the hardware components are not available in that environemnt. Often however, it is sufficient to run the backend in a virtual environment, for example if you only plan to change the flask-api (which does not interact with any hardware component at all). In this case, using a virtual machine is advisable, since it offers a faster setup time. In the following, we will discuss the setup of both environments in more detail.

Setting up a Virtual Machine:

To install pib’s backend, you first need to download and install VirtualBox. Download links for Windows, macOS and Linux can be found here. Additionally, if you plan to install VirtualBox on a Debian-based System, you can alternatively run

During installation, you might get a notification that the dependency “Python Core / win32api“ is missing and you will be asked, if you want to continue anyway. You can safely ignore this warning and continue the installation-process. Once VirtualBox is installed successfully, you can now download the ubuntu 22.04.4 Desktop image. When this is done too, start VirtualBox and create a new virtual machine, by clicking the 'New' button:

Open

A new window will open with several options on how to configure your new vm. The two most important options are the ‘ISO Image', where you should select your downloaded ‘ububntu 22.04.4 Desktop’-image, and the hard disk size, where you should select at least 32GB. You also need to check the 'Skip Unattended Installation'-checkbox:

When this is done, you can now click the 'Finish'-Button and a new vm will be created.

After you have created the new vm, you can start it by simply double-clicking it in the list of available machines on the left. You can now perform a normal ubuntu-installation, where you create a user ‘pib’ with password 'pib’, just the way you would do on a physical pib. After installation is done, you can now turn off the machine.

If you want to connect a remotely deployed frontend to the backend on the vm, or if you want to develop on the vm and want to connect to it via VS-Code’s Remote Development Functionality, you need to do so via the vm’s ip-address. In order to do that, you need to change the vm’s network-settings. Right-Click on your newly created vm and select ‘Settings’:

Go to the ‘Network’-tab, check the ‘Enable Network Adapter’-checkbox, select the ‘Bridged Adapter’-option from the ‘Attached to’-dropdown and finally click the ‘OK’-button to apply the settings.

Theoretically, you could now run a setup-script on this machine, however we recommend you not to do so. During development, you frequently have to run setup-scripts on new machines with a clean ubuntu installation (i.e. a machine, where the setup-script has not run yet) and doing so is very time-consuming. One way to alleviate this, is to skip the ubuntu-installation process, by not creating a new vm from scratch, but by keeping your intial vm (where you did not run the setup-script) as a base-vm, and to create all subsequent vms (where you actually run the setup-script), by cloning the base-vm. Cloning can simply be done by right-clicking your base-vm and selecting the 'clone' option:

A window will open, which will present you several options on how to configure the clone of your vm. You choose an arbitrary name for clone and the path, were it should be saved (you can probably stick with the default option). You can also specify the type of the clone. Here, you should select ‘full clone'. Otherwise you can stick with the default options. After you are done configuring the clone, you can click 'Finish’.

If you are working with virtual-machines, we also recommend you to install the Guest Additions which will probably make your development process easier, by allowing convenience functionalities such as a shared clipboard (which allows you to f.e. copy something to your cliboard on your host and then paste it within your vm) and others. It is best to install these on your base-vm, so that you have them available with each new clone that you create.

Setting up a physical pib

As an alternative to running the setup-script on a virtual-machine, you can of course also run it on a raspberry pi, that is connected to a physical pib. We assume here that you already have the hardware assembled. If you want to install pib’s software on the raspberry pi, you need a 32GB microSD card, where you can install the software on. Next, you need to install the Rasperri Pi Imager on your local system. The imager can be used to install a new opreating system on your sd-card. Instructions on how to use the imager to install a new operating system can be found here. You should choose ‘Raspberry Pi 4' as the device and ‘Ubuntu Desktop 22.04 LTS (64-bit)’ as the operating system (found via: “Other general-purpose OS → Ubuntu → Ubuntu Desktop 22.04 LTS (64-bit)”). Once this process has completed, you can insert the microSD card into your pi and perform a regular ubuntu installation, where you create a user 'pib' with password 'pib'.

Editing code on your remote machine

After making changes to pib’s backend software, you somehow need to make these changes available on the machine where your actual backend is running, to see the results. There are multiple ways to achieve this. One option that you have, is to directly change the code that is located in the ‘/home/pib’ directory of your pi/vm. The easiest way to do so, is by using VS-Code's Remote Development feature. If you followed the VS-Code installation instructions above closely, you already have the Remote Development Extension Pack installed. Otherwise you should now install this packet (more information on how to install VS-Codes Extensions can be found in the 'IDE' section above). Now you can connect to your remote machine by clicking the icon in the far bottom left corner of the screen. A dropdown appears, where you should choose 'Connect to Host':

Type in ‘pib@<ip-address of your pi/vm>' and hit enter. You now have to enter pib’s password. After this is done, you are now connected to your remote machine. You can now open any folder, edit files and run commands on your remote machine directly from within VS-Code. One thing that needs to be mentioned, is that VS-Code extensions that you have installed on your host machine are not available on your remote machine automatically, instead you need to install them again, while connected to the remote machine.

The alternative do editing files directly on your pi/vm, is to edit them on your local machine first and subsequently to transfer them to your remote machine. If you are using Windows on your local machine, an easy way to achieve this is by using WinSCP, which can be downloaded here. Once you have installed and started the application, a login window will open automatically:

Click the ‘New Site' option on the left. Enter ‘pib@<ip-address of pi/vm>’ as the 'Host name' and then enter pib’s password. You can now either save or login directly. If you login, you can now exchange files with your remote machine via drag-and-drop. More detailed guides on the usage of WinSCP can be found here.