Open Roberta Lab

Introduction

The steps below explain how to get started with the sources of the OpenRoberta lab. If you just want to run the server locally only, please have a look into the Wiki - Docker Installation or the (outdated, but working) description Wiki - Installation.

If you want to contribute, please get in touch with us, see Wiki - Community, before you start. Please also check our wiki for development procedure, coding conventions and further reading. We use the Github issue tracking system. Please file issues in the main project openroberta-lab.

All of our production and test systems run on Linux servers. Most of our developers use Linux laptops. The following instructions are valid for Linux machines. Nevertheless you can follow the steps on a Win* machine. Please leave out the installation of cross compilers, because not all exist/work on Win*. Without crosscompiler you can do almost everything (start the server, experiment with the frontend, create user, use the data base, change the lab by editing our sources, ...), except cross compilation of course.

Prerequisites

You need Java JDK >= 1.8 and JAVA JDK <= 13.0.2 (e.g. openjdk-11-jdk), Maven, Git and Python3 together with pip3 and python3-serial. A typical install on ubuntu:22.04 as superuser with apt is (other systems are similar):

apt-get update
apt-get install openjdk-11-jdk
apt-get install maven
apt-get install git
apt-get install npm
apt-get install python-is-python3
apt-get install python3-pip
apt-get install python3-serial
# check the installation:
java --version
mvn --version
git --version
python --version
pip --version

Cross Compiler (optional)

Binaries

If you would like your local server to compile code for the different systems, you need to install software (crosscompilers, libraries, ...). It is recommended to download them to a user-defined directory, such as /opt/compilers/, as this will save us the trouble of finding the correct path to the binaries later on!

• Arduino based robots
  • sudo apt-get install libusb-0.1-4
  • sudo apt-get install binutils-avr gdb-avr avrdude
  • download and unpack avr-gcc to a directory of your choice.
• NXT
  • sudo apt-get install nbc
• Calliope
  • sudo apt-get install srecord libssl-dev
  • download and unpack the latest gcc-arm-none-eabi to a directory of your choice.
• EV3 c4ev3
  • sudo apt-get install g++-arm-linux-gnueabi
• Bionics4Education
  • download and unpack xtensa-esp32-elf to a directory of your choice.

Next, add all of the downloaded binaries to the PATH. The <path-to-the-compiler-folder> should be replaced with the download directory (created earlier) followed by the compiler folder:

echo export PATH="$PATH:<path-to-the-compiler-folder>/bin" >> ~/.profile`

Resources

The cross-compiler need resources to work properly (header files, libraries, ...). These resources change little over time and are stored in the 'ora-cc-rsc' repository.

Please clone that directory and build it using mvn clean install. If the resources are not available, everything works fine, but running programs on real robots doesn't work, because the cross-compiler will fail.

Installation

Step 1: Clone the repository and compile

The source of the OpenRoberta Lab is stored in the Github repository 'openroberta-lab'. We use develop to the default branch of our repository. If you clone our repository, you'll get develop first. In general this is a stable version. You can deploy a local version as described below. If you want to run the currently deployed version, please checkout master before building.

After a fresh git clone you get the openroberta-lab project folder. It includes almost everything you need to setup and extend your own openrobertalab server. License information is available in the docs folder. Btw: if you use many repositories, put all of them into a common directoy as ~/git.

git clone https://github.com/OpenRoberta/openroberta-lab.git # get the repository
cd openroberta-lab                                           # cd into repository
mvn clean install                                            # generate the server, at the end: build success
npm install && npm run build                                 # build the frontend, some lines, must show no error

Takes some time.

Step 2: Make sure you have a database and start the server

The two main shell scripts to work with are ./admin.sh and ./ora.sh. They have a lot of commands and options. Call the scripts without parameter or with -h to get a help message. ./admin.sh is used for data base administration and server start, ./ora.sh for server export and start. If you have a fresh clone of the server, make sure that the OpenRobertaServer folder has a subfolder db-embedded with a database inside. If you don't have a database, you can create an empty database with

./admin.sh -git-mode create-empty-db

If you try to create a new database, but one exists, the old one is not changed and the command has no effect. The new database is found in the folder ** OpenRobertaServer/db-embedded**. We needs a database to store user accounts, programs, etc. We use HyperSQL. Other database systems (MySql, Postgres, ..., oracle, db2, ...) would work, too. There are no special requirements on the database, that would exclude one. Only a Hibernate binding and a full transaction support is needed.

Now use one of the following commands to start the server

./admin.sh -git-mode  start-from-git     # writes logging to ./admin
./ora.sh  start-from-git                 # writes logging to the console

If you did not install the crosscompiler resources, everything works fine (programming, simulation, code generation, user management, ...), except of generation of binaries for robot systems.

The URL for your browser is http://localhost:1999 That's it!

Creating an installation outside of the git repo

Often you want to run an openroberta installation of a fixed version for some time. This is easy. Let's assume, that you want to use the (non-existing) directory /data/my-openroberta.

mvn clean install && npm run build         # generate the server in the git repo
./ora.sh export /data/my-openroberta gzip  # export to the target directory. gzip compresses the static web resources fpr better performance.
cd /data/my-openroberta                    # the export command supplies an administration script admin.sh, which is different from the one in the git workspace
./admin.sh create-empty-db                 # create an empty db at ./db-server - of course you may copy an old database to that location
./admin.sh start-server                    # spawns two processes: a database server and the openroberta jetty server

This kind of installation is useful for small installations. True productive systems need more support. We deploy our openroberta installation using docker. It is described in detail in the file README.md of the repository openroberta-docker. In the repository you will find everything needed to create images and start them. You can try it. If there are problems, you can contact us.

Development notes

You should import the projects of the openroberta-lab repository locally into IDE's such as Eclipse or IntelliJ!

The project OpenRobertaServer contains the server logic, that accesses

• a database with Hibernate-based DAO objects
• plugins for various robots which are supported in OpenRoberta
• services for browser-based clients
• services for robots connected to the lab either by Wifi or USB

The server is made of

• an embedded jetty server exposing REST services
• the services are based on jersey
• JSON (sometimes XML or plain text) is used for data exchange between front end, robots and server

Furthermore, the project OpenRobertaServer contains in directory staticResources for the browser client

• HTML and CSS
• Generated Javascript under /js (this should not be edited!)
  • Javascript libraries based on jquery and bootstrap for the frontend
  • assertions (DBC), ajax-based server calls (COMM), logging (LOG) and
  • javascript resources for blockly
  • controller and models written in Javascript, which implement the GUI

The TypeScript and Javascript sources can be found in OpenRobertaWeb/
To work with the frontend (e.g. compiling the sources) we use the following npm scripts:

• npm run build - build the sources
• npm run build:sourceMap - build the sources and generated source maps for debugging
• npm run watch - build the sources on change
• npm run watch:sourceMap - build the sources on change and generate source maps for debugging
• npm run format - formats all javascript and typescript source files
• npm run format:check - check if all javascript and typescript files are formatted

Attention: Only check in those generated files build with npm run build or npm run watch!

Testing

To run backend tests, use mvn test. Running mvn clean install will make a stable, reproducible build with all unit tests executed.

To run the integration tests you have to supply an additional flag: mvn clean install -PrunIT. These tests expects, that all crosscompiler are installed.

Some Frameworks used

We use Blockly, it is located in a separate repository. The build of the blockly is only done in the OpenRoberta/Blockly project and then copied to the OpenRobertaServer/staticResources. You can not build Blockly in OpenRobertaServer project directly.

We use BrowserStack for Cross-Browser Testing

Have a look at the notes in LICENCE and NOTICE