Wiki

Running RML

rml is currently a command-line tool called, naturally, rml. When you call it without arguments, it prints usage instructions:

rml --     RobotMetaLogger, a framework for logging and working 
            with robot execution data.

Usage: rml [-c config] <command> [args]

Command is one of:
    help    Display this help.
    init    Initialize a new log destination directory.
    run   Record a new run of logs, with all the configured sources.
    time    Continuously print out the time with sub-second accuracy

Global options:
    -c    Specify configuration file. [Default: $(cwd)/.rml/config.json]

Run "rml help <cmd>" to get more info, if available.

To stop logging, press "Ctrl-C".

Initial Steps

To start a new recording set, do
  1. create a new directory to hold data files
  2. call rml init in the directory

The last step will create a sub-directory .rml and a file config.json in that directory. In the future, it is planned that this configuration can be maintained using rml itself, but for now, you'll have to edit it manually. The configuration is pretty simple, though.

Configuration

RML uses a JSON based configuration file. After init (see above), it looks as follows:

{
    "rml_cfg": {
        "environment": {}, 
        "probes": {}, 
        "state": {
            "last_run": 0, 
            "last_session": 0
        }, 
        "version": 0.3
    }
}

The important section is the "probes"-section: All data-sources are called probes, and they have the following common arguments:
  • class: What kind of probe it is. At the moment, the following classes are supported:
    • event: Message exchanged between software components
    • camera: All sorts of camera devices
    • screen: Screen capture
    • audio: Audio data
  • type: The exact type of probe. The known types depend on the class. See below for a list.
  • location: Where to store logging data. This can either be a file or a directory, depending upon the type of the probe. It will be created by the probe itself, relative to the current working directory.

Known Probe Types

A probe configuration looks as follows:

"name": {
  "class": "one-class-of-the-above",
  "type": "a-specific-instance-as-below",
  "location": "where to log",
  [...]
}

Where the [...] may contain optional arguments.

The "probes"-section can hold multiple probe configurations, separated simply by a comma.

Event Probes

These kind of loggers capture raw event data from support middlewares. At the moment, XCF and RSB are supported for capture.

Their class is "event"

xcf

Logs events from the XCF middleware

The location will be an XML file, and should have a .xml extension, though this is not required.

This probe does not have arguments. However, all the usual XCF environment variables are used.

Note This logger does not capture binary attachments.

rsb

Logs events from the RSB middleware

The location will be a TIDE-format logfile and is required to have a .tide extension.

Required Arguments
  • spreadhost Hostname of the machine where the spread daemon used by RSB runs
  • spreadport Port number of the spread daemon

Camera Probes

These probes capture visual or audio-visual data. Their class is "camera".

opencv

This probe captures a locally-attached camera, e.g. a webcam, and stores it as an MJPEG-file.

Required Arguments
  • camera_num Number of the camera, starting from 0
Optional Arguments
  • display Boolean. If true, will display the image during capture. Defaults to False.

network_h264

Captures H264 data from network cameras. This probe could easily be extended to also capture other video format,s but for the moment, it only uses H264, because that is what most RTSP streams deliver.

Required Arguments
  • url The rtsp url, e.g. rtsp://192.168.1.1/axis-media/media.amp
  • width Width in pixels of the incoming video-stream
  • height Height in pixels of the incoming video stream
  • fps Framerate of the incoming video stream
Sometimes required arguments
  • username Username to use for RTSP authorization. Required for protected streams.
  • password Password to use with username. Required for protected streams
  • noaudio 1 for no audio capture, defaults to 0. Required when the video stream has no audio.

xcf

Captures image streams from XCF publishers. When the location argument ends in ".mkv", it will create an H264 stream on the fly, stored in a matroska container. Otherwise, it will create a directory with each frame individually encoded as jpeg.

Required arguments
  • publisher Name of the image publisher

Class screen, Type ffmpeg

Captures the local X11 screen using ffmpeg. The output will be an XVID file.

Required Arguments
  • display The display number. No default, but usually "0.0" is the first screen.
Optional Arguments
  • fps Frames per seconds to record. Defaults to 12.5
  • width Width of the capture area. Defaults to the full screen width.
  • height Height of the capture area. Defaults to full screen height.
  • scale Scale factor by which the resulting video will be shrunken. Defaults to 1, i.e. no shrinking.
  • quality Recording quality. Defaults to 3
  • bitrate Bit rate for the recording. Defaults to width*height/50

Class audio, Type gstreamer-tcp

This probe captures an audio source exported via gstreamer's tcp protocol. A corresponding export script is in source:src/shell/capture/linux-audio-tcp.sh

Required Arguments
  • host Where the server is running
  • port The port number. A typical port is 4953
Optional Arguments
  • container A string giving the container type. At the moment, "wav" and "matroska" are supported. wav is the default format, but only supports 1 or 2 channels. For more channels, matroska must be used.
  • protocol Which gstreamer protocol is being used. Defaults to 1 (for gdp encoded packets). May also be 0, for raw transport. In the case, the "format" argument is required.
  • format gstreamer caps string giving the format of the incoming data.