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- create a new directory to hold data files
- 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.
spreadhost
Hostname of the machine where the spread daemon used by RSB runsspreadport
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 Argumentscamera_num
Number of the camera, starting from 0
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 Argumentsurl
The rtsp url, e.g. rtsp://192.168.1.1/axis-media/media.ampwidth
Width in pixels of the incoming video-streamheight
Height in pixels of the incoming video streamfps
Framerate of the incoming video stream
username
Username to use for RTSP authorization. Required for protected streams.password
Password to use with username. Required for protected streamsnoaudio
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 argumentspublisher
Name of the image publisher
Class screen, Type ffmpeg¶
Captures the local X11 screen using ffmpeg. The output will be an XVID file.
Required Argumentsdisplay
The display number. No default, but usually "0.0" is the first screen.
fps
Frames per seconds to record. Defaults to 12.5width
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 3bitrate
Bit rate for the recording. Defaults towidth*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 Argumentshost
Where the server is runningport
The port number. A typical port is 4953
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.