kobbled / rossum

A CMake-like build file generator for Fanuc Robotics (Karel) projects.

rossum

This is rossum, a CMake-like build file generator for Fanuc Robotics (Karel) projects.

Overview

This tool introduces a package based workflow for Karel development: packages are directories that contain a marker file (a manifest) that contains some metadata describing the dependencies of that package and any translatable targets. Detection of packages and generation of the build file is done once at configuration time, relying on the build tool's dependency resolution to build all targets in the correct order.

Installation

1. Install Git & Python
2. (optional) Create a python virtual environment python -m venv <name>
3. Install Ninja from https://github.com/ninja-build/ninja/releases. Download the ninja-win.zip file, and extract to a user specified directory. Make sure you add this to your environment Path.

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";" + "path\to\ninja", "User");

4. Clone the repo and submodules to a user specified directory. If using an python virtual environment this can be cloned within your venv if you so choose.

git clone https://github.com/kobbled/rossum --recurse-submodules

5. Run the install file in a powershell terminal, with the optional argument specifying the path to your created venv.

. ./install.ps1 <path\to\venv>

Alternatively a convenience distribution can be downloaded from https://github.com/kobbled/rossum/releases. Simply extract to a user specified location, and add this location to your environment Path.

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";" + "path\to\rossum-distrib", "User");

Important

make sure you add any external libraries or projects that are dependencies (such as Ka-Boost) to the environment variable ROSSUM_PKG_PATH. See Environment Variables for more details.

Note

On windows machines the python alias can be overwritten by the py launcher where python is started in the terminal with py -3. The batch files are written with the python key. To create the alias type this into powershell:

Set-Alias -Name python -Value "path\to\Python\Python39\python.exe"

replacing the value with the full path to the python executable in your PATH environment variables.

Warning

If you installed rossum with the "install.ps1" script the steps in Requirements, and Dependencies are not needed. If you are trying to setup in a linux/unix environment follow the steps below.

Requirements

• Rossum was written in Python 3. Python dependencies can be installed with

pip install -r requirements.txt

• Add the ./bin directory of Rossum to your environment Path
• The generated Ninja build files require a recent (> 1.7.1) version of Ninja to be present. Please install Ninja on your machine, and make sure the binary is located on your envrionment Path.
• FANUC Roboguide must also be installed with OPLC bin programs, maketp, ktrans, and setrobot. These tools can be typically found in C:\Program Files (x86)\FANUC\WinOLPC\bin. An emulation of your workcell should be made through Roboguide or OLPCpro, typically stored in %USERPROFILE%/Documents/My Workcells. Once a workcell has been created, and robot.ini file needs to be generated in the root of your rossum project. The robot.ini file can be generated by typing setrobot into a terminal opened in the root directory of your project, and selecting the appropriate workcell.
• Add the following to your environment variables, and change the values according to your system

# Rossum specific variables
set ROSSUM_CORE_VERSION=V910-1
set ROSSUM_PKG_PATH \path\to\rossum\dependency\packages
set ROSSUM_SERVER_IP 127.0.0.1

See Environment Variables for more details on usage.

Note

If using TP+, and link to you controller environment file must be placed in the robot.ini like: ENV=C:\path\to\env.tpp

Important

Full path to env.tpp must be specified. DO NOT use relative paths here.

Dependencies

• ktransw must be installed on your system for Rossum to compile karel files. follow the instructions here for installation. ktransw is included as a submodule of this package in "./deps/ktransw". Make sure that "./deps/ktransw/bin", and "./deps/ktransw/gpp" are on your environment Path.
• yamljson2xml is required to convert .yaml. or .json files to xml to be sent to the controller. Currently Fanuc cannot read or parse .yaml. or .json, but can read .xml files. Follow this installation instructions here, and make sure the necessary locations are added to your environment Path.

Examples

Please see rossum_example_ws for an example workspace with some packages that show how to use rossum.

currently handled files

• Karel (.kl)
• LS files (.ls)
• TP-Plus (.tpp)
• JSON (.json)
• YAML (.yaml)
• CSV (.csv)
• FANUC Dictionary (.utx)
• FANUC Form (.ftx)

Note

Look at the User Form example in rossum_example_ws, basic_test\lib_a. Preprocessor directives have been expanded in .utx, and .ftx files using ktransw. In order to properly compile dictionary files, ninja might have to be run twice to first create the karel include file, and then build the accompanying karel file.

Usage

standard

  mkdir C:\foo\bar\build
  cd C:\foo\bar\build
  rossum C:\foo\bar\src
  kpush

delete files from build dir on robot controller

kpush --delete

clean out build file

  cd C:\foo\bar\build
  rossum --clean

build source files from package.json

  cd C:\foo\bar\build
  rossum C:\foo\bar\src -s

output test files with source files from package.json

  cd C:\foo\bar\build
  rossum C:\foo\bar\src -t -s

build programs to interface karel routines in TP programs

  cd C:\foo\bar\build
  rossum C:\foo\bar\src -i

Note

This option depends on the kl-TPE,kl-pose, and kl-registers packages from the Ka-Boost libraries. If Ka-Boost is installed make sure to add theses libraries to the dependencies of the package you are build in with this option.

{
  "depends" : [
    "registers",
    "TPElib"
  ]
}

keep preprocessor output in %TEMP%

  cd C:\foo\bar\build
  rossum C:\foo\bar\src -s -g

build all source files from dependencies

  cd C:\foo\bar\build
  rossum C:\foo\bar\src -s -b

build all tp interfaces from dependencies

  cd C:\foo\bar\build
  rossum C:\foo\bar\src -i -b

build with user macro %define DEBUG

  cd C:\foo\bar\build
  rossum C:\foo\bar\src -DDEBUG=TRUE

--help output

usage: rossum [-h] [-v] [-V] [-q] [--rg64] [-c ID] [--support PATH] [-d]
              [--ktrans PATH] [--ktransw PATH] [-n] [-p PATH] [-r INI] [-s]
              SRC [BUILD]

Version 0.1.7

A cmake-like Makefile generator for Fanuc Robotics (Karel) projects
that supports out-of-source builds.

positional arguments:
  SRC                   Main directory with packages to build
  BUILD                 Directory for out-of-source builds (default: 'cwd')

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         Be verbose
  -V, --version         show program's version number and exit
  -q, --quiet           Be quiet (only warnings and errors will be shown)
  --rg64                Assume 64-bit Roboguide version.
  -c ID, --core ID      Version of the core files used when translating
                        (default: V7.70-1). Use the 'ROSSUM_CORE_VERSION'
                        environment variable to configure an alternative
                        default without having to specify it on each
                        invocation of rossum.
  --support PATH        Location of KAREL support directory (default: auto-
                        detect based on selected core version and FANUC
                        registry keys)
  -d, --dry-run         Do everything except writing to build file
  --ktrans PATH         Location of ktrans (default: auto-detect)
  --ktransw PATH        Location of ktransw (default: assume it's on the
                        Windows PATH)
  -n, --no-env          Do not search the ROSSUM_PKG_PATH, even if it is set
  -p PATH, --pkg-dir PATH
                        Additional paths to search for packages (multiple
                        allowed). Note: this essentially extends the source
                        space.
  -r INI, --robot-ini INI
                        Location of robot.ini (default: source dir)
  --ftp                 Use IP address in environment variable 
                        'ENV_SERVER_IP' to send files in build folder to
                        Controller with 'kpush' command.
  -s, --buildsource     build source files in package.json.
  -b --buildall         build all dependencies as well
  -g --keepgpp          keep gpp preprocessor output in %TEMP% folder to
                        evaluate bugs.
  -tp --compiletp       compile .tpp files into .tp files. If false will 
                        just interpret to .ls.
  -t  --include-tests   include test files in build
  -i  --build-interfaces   build tp interfaces for karel 
                        routines specified in package.json.
                        This is needed to use karel routines within a tp program
  -D  /D                Define user macros from command line
  --clean               clean all files out of build directory

robot.ini file example

create robot.ini file in the top level of the source directory calling setrobot through a command prompt, and selecting the correct workcell created with Roboguide. Ftp, and Env will need to be added afterwards as they are Rossum specific directives.

[WinOLPC_Util]
Robot=\C\Users\<user>\Documents\My Workcells\cell\Robot_1
Version=V9.10-1
Path=C:\Program Files (x86)\FANUC\WinOLPC\Versions\V910-1\bin
Support=C:\Users\<user>\Documents\My Workcells\cell\Robot_1\support
Output=C:\Users\<user>\Documents\My Workcells\cell\Robot_1\output
Ftp=127.0.0.1
Env=C:\Users\<user>\Documents\My Workcells\cell\tpp\vars.tpp

package.json file example

{
  "manver" : "1",
  "project" : "kl-lib",
  "description" : "",
  "version" : "0.0.2",
  "license" : "MIT",
  "author" : "name",
  "source" : [
    "src/source.kl"
  ],
  "includes" : [
    "include"
  ],
  "depends" : [
    "ktransw-macros",
    "Strings",
    "math",
    "registers",
    "TPElib"
  ],
  "tp" : [
    "tp/move.ls"
  ],
  "tp-interfaces" : [
    {"routine" : "source__func01", "program_name" : "func01"},
    {"routine" : "source__func02", "program_name" : "func02"},
    {"routine" : "source__func02", "program_name" : "func02", "default_params" : {"2": 1, "3": "default_string"}},
  ],
  "forms" : [
    "forms/frmnmeeg.ftx"
  ],
  //macro commands set in programs. (for example building for debugging or production)
  "macros" : [
    "DEBUG=TRUE",
    "BUILD_LOG=FALSE"
  ],
  //test files to build when using the -t option
  "tests" : [
    "test/test_source.kl"
  ],
  //includes needed for tests
  "tests-includes" : [
    "test/configs"
  ],
  //test dependencies
  "tests-depends" : [
    "display",
    "KUnit"
  ],
  //Only builds TP files when -t option is specified
  "tests-tp" : [
    "test/tp/test_move.tpp"
  ],
  // This option is used to create a karel hash table from the TP+ environment file specified in robot.ini file
  "tpp_compile_env" : {"name" : "tppenv", "clear" : false, "config" : "env"}
}

tp-interfaces

Teach pendant interfaces are a way of exposing karel routines, for usage in teach pendant (TP) programs. Inherently you are not allowed to access karel routines with the CALL function in TP programs. You are able to call karel programs within TP programs. Rossum provides a way to automatically create a karel program wrapper around a specified routine. For instance if you want to expose a routine definition:

ROUTINE func01(p : XYZWPR; i : INTEGER; r : REAL) : INTEGER

and create a wrapper program called tp_func01, you can define an interface in the package manifest:

"tp-interfaces" : [
    {"routine" : "func01", "program_name" : "tp_func01", "default_params" : {"2": 1, "3": 0.0}}
  ]

This will output a karel program to <src>/tp/ . If there is a return type the last arguement will be the register number to store the result in.

If an input argument is a position type, the corresponding TPE arguement is the position register number where the input data is stored.

currently handled types

• INTEGER
• REAL
• STRING
• XYZWPR
• JOINTPOS

Default arguements can also be specified using the "default_params" field. where the key:value pair is the argument number (index starting at 1), and the default value you would like to specify.

In the case for "func01" the 2nd integer argument will default to 1 if not included, and argument 3 will default to 0.0. There currently is no mechanism to leave argument 2 blank, but declare a value for argument 3. Therfore all subsequent arguments also have to be excluded for default arguments to work. This means that the arguments must be ordered in a manner that subsequent arguments would not need to be declared if the current argument is not specified.

user macros

package/project wide pre-processor macros can be defined either from the command line or the package manifest. From the command line macros are invoked the same way they are in GPP (see GPP documentation), with -Dname=val, or /Dname=val. Macros can be included in the package manifest as shown in example package.json.

Environment variables

# environment pointers
set PATH=%PATH%;C:\path\to\rossum\bin
set PATH=%PATH%;C:\path\to\rossum\deps\ktransw\bin
set PATH=%PATH%;C:\path\to\rossum\deps\ktransw\gpp
set PATH=%PATH%;C:\path\to\rossum\deps\yamljson2xml\src

# Rossum specific variables
set ROSSUM_CORE_VERSION=V910-1
set ROSSUM_PKG_PATH \path\to\rossum\dependency\packages
set ROSSUM_SERVER_IP 127.0.0.1

rossum checks for the existence of two environment variables and uses their contents to change its behaviour.

ROSSUM_PKG_PATH

The ROSSUM_PKG_PATH should contain (a) path(s) to one or more directories containing rossum packages. All directories will be searched when running rossum so that the full paths of these packages do not need to be specified, merely the name of the package.

For example if you have the dependency Strings on your project, you would add the location where you put the Strings repo (i.e. C:\path\to\rossum\dependency\packages) to ROSSUM_PKG_PATH. Then in the package.json file simply add the name of the package:

"depends" : [
    "Strings"
  ],

Rossum now has visibility to the Strings package.

ROSSUM_CORE_VERSION

The ROSSUM_CORE_VERSION variable can be used to specify a 'system wide' default core version that should be used for all invocations of ktransw, unless the default is overriden using the --core option.

Example: to make version 8.30 of the support files the default set ROSSUM_CORE_VERSION to V8.30-1.

Glossary

Terminology used by rossum.

package

A directory containing any number of source and header files, organised into src and include sub directories, along with a JSON package manifest. The manifest declares translationable binary targets and additional meta-data such as build dependencies (other rossum packages), author, version and test binaries.

workspace

A directory containing a set of rossum compatible packages. Note that while possible, packages are typically not directly stored in the top-level workspace directory, but in a source space sub directory.

source space

The sub directory of the workspace that contains a set of of rossum compatible packages. Usually named src.

build space

The sub directory of the workspace that will store all the build output (p-code files).

build file

The ninja build file generated by rossum at the end of the configuration phase.

Disclaimer

WinOLPC, OlpcPRO and Roboguide are products of Fanuc America Corporation. The author of rossum is not affiliated with Fanuc in any way.