Adding a new plugin

This page is under construction.

The first decision to make is whether the new plugin is standalone or can be categorized under a similar plugin as a sub plugin (e.g. mbot under RobotArdu).

Each plugin is a separate project that uses the OpenRobertaRobot as a base. It provides basic interfaces, blocks and functionalities for the robot specific plugin to implement. The OpenRobertaServer project uses the plugins to deliver the robot specific functionality.

The following two sections show a general overview of tasks for each of these cases. Details are either covered in their own wiki pages or in following sections below.

Standalone plugin tasks:

• Under construction. For a general overview you can follow the latest commits on the feature/orb branch, a new plugin for a webView based robot.

Sub plugin tasks:

• Basic plugin setup (based on this commit)
  • create <robotname>.properties file in the parent plugin directory (see Properties)
  • add toolboxes and default configuration
  • add a hardware visitor interface which defines capabilites of the robot
  • add workers and associated visitors
    • the codegeneration worker + visitor is always needed
    • most of the time a compiler worker is necessary
  • add <robotname> to robot.whitelist in openroberta.properties
  • add icon to typicons
  • add case <robotname> to RobotDownloadProgram in the server module (this should be removed to completely decouple plugins)
  • add tests for robot specific functionalities
• Add necessary cross compiler resources to ora-cc-rsc
  • Arduino based robot: arduino-resources
    • add or reuse a packing.ino
    • add or reuse build_project.sh
    • add or reuse compile_resources.sh
    • add your robot to compile_all.sh
    • add new external libraries to Dockerfile and packing.ino
    • add new custom libraries to RobotArdu/libraries
    • create a new release
    • update linked release version in ora-cc-rsc
  • Other robot:
    • add resources directly to suitable directory in ora-cc-rsc
• Add blocks to blockly (this process will change soon) (based on this commit)
  • add case <robotname>: to core/constants.js
  • reuse implementation of existing action blocks -> sometimes if this.workspace.devices == '<robotname>' is required in robActions.js
  • add new action blocks -> robActions.js, see this TODO
  • add or reuse sensor blocks -> robSensorDefinitions.js, don't forget to also add an entry to sensorsAll on the bottom, see this TODO
  • add new configuration blocks -> robConfigDefinitions.js, see this TODO
    • add pins
  • new messages -> add english message to robMessages.js and translations to <lang>.json
  • add testing playground
  • build with python build.py and closure-library downloaded (only works on Unix, use WSL on Windows)
  • copy built files to openroberta-lab\OpenRobertaServer\staticResources\blockly
• Connection (for details see Properties):
  • autoConnection or jsPlay -> nothing should be needed (I am not 100% sure yet)
  • token -> Add robot to the Connector (based on this commit)
    • add <robotname> to specific *RobotType
    • add implementation to specific *Detector
    • add implementation to *Communicator
    • add <robotname> to wired-robot-ids.txt if it is wired
  • webView -> see this TODO

Explanations

Properties

The <robotname>.properties file is the entrypoint to your plugin. Here, almost everything related to your robot is specified or linked. Let's take the properties file of unowifirev2 as an example.

First, the robots parent group (optional) is specified, together with the factory, which should almost always be RobotFactory, and the directory for cross compiler resources in the ora-cc-rsc repo.

robot.plugin.group = arduino
robot.plugin.factory = de.fhg.iais.roberta.factory.RobotFactory
robot.plugin.compiler.resources.dir = RobotArdu/

The next entries are pretty obvious, which file extension the source and binary files of your robot have. binary is not limited to binary blobs and may also be zip as used for the festobionics robot.

robot.plugin.fileExtension.source = cpp
robot.plugin.fileExtension.binary = hex

The toolboxes and default program/configuration decide what the user has available in the frontend. These consist of blockly XMLs and should also be saved the Java resources. As you can see unowifirev2 uses everything from the generic arduino subdirectory because it shares its available blocks with similar Arduino based robots.

robot.program.toolbox.beginner = /arduino/program.toolbox.beginner.xml
robot.program.toolbox.expert = /arduino/program.toolbox.expert.xml
robot.program.default = /arduino/program.default.xml
robot.configuration.toolbox = /arduino/configuration.toolbox.xml
robot.configuration.default = /arduino/configuration.default.xml

This is just some general information, the pretty display name for the frontend and a help page which is linked through the i on the start popup. By using en and de different info pages for these two languages may be used.

robot.real.name = Nepo4Arduino Uno Wifi Rev2
robot.info.en = https://www.arduino.cc/

robot.configuration decides whether the robot has a visible configuration which can be changed by the user or a placeholder image with some generic information. This is useful for very simple robots without any additional ports. The type is limited to new or old-<sensorprefix>. The name should make clear that new should be used.

robot.configuration = true
robot.configuration.type = new

The connection specifies how the robot will recieve the program. Available options are token, autoConnection, webView, jsPlay and arduinoAgentOrToken. token needs an intermediate program that generates a token like our EV3leJOS firmware or the Connector. autoConnection does not need an active connection and provides a downloadable binary file through the browser, which can be transferred to a robot simulating an USB drive. webView uses the Android app to interpret our intermediate simulation code and transfer it to the robot on a command by command basis. jsPlay is a specific method for the edison robot, which recieves its program through audio. arduinoAgentOrToken is deprecated and should not be used for new robots.

robot.connection = token

This specifies whether the robot has an attached simulation. This has some additional requirements and is explained here TODO.

robot.sim = false

This file provides information necessary for the connection between the Java classes and the blockly blocks. Here, the arduino.yml provides additional blocks based on robotCommon.yml from the generic OpenRobertaRobot project.

robot.descriptor = classpath:/arduino.yml

robot.helperMethods = classpath:/common.methods.yml

The workers necessary for this plugin. As can be seen, the unowifirev2 robot uses a specific worker for validation but can reuse some generic implementations for the others.

robot.plugin.worker.validate = de.fhg.iais.roberta.worker.validate.UnoConfigurationValidatorWorker
robot.plugin.worker.collect.hardware = de.fhg.iais.roberta.worker.collect.ArduinoUsedHardwareCollectorWorker
robot.plugin.worker.collect.method = de.fhg.iais.roberta.worker.collect.ArduinoUsedMethodCollectorWorker
robot.plugin.worker.generate = de.fhg.iais.roberta.worker.codegen.ArduinoCxxGeneratorWorker
robot.plugin.worker.setup = de.fhg.iais.roberta.worker.compile.ArduinoCompilerSetupWorker
robot.plugin.worker.compile = de.fhg.iais.roberta.worker.compile.ArduinoCompilerWorker
robot.plugin.worker.transfer = de.fhg.iais.roberta.worker.TransferWorker

Finally, the workflows specifiy the capabilities of the plugin. Each workflow can use any of the workers to generate different outputs. For more information on workers and workflows check this TODO.

robot.plugin.workflow.showsource = validate,collect.hardware,collect.method,generate
robot.plugin.workflow.compile = validate,collect.hardware,collect.method,generate,setup,compile
robot.plugin.workflow.run = validate,collect.hardware,collect.method,generate,setup,compile,transfer
robot.plugin.workflow.runnative = setup,compile,transfer
robot.plugin.workflow.compilenative = setup,compile