Robotics Service Bus » RSBag

h1. @bag-record@

{{>toc}}

h2. Introduction

The @bag-record@ program can be used to capture certain RSB events in a running system and store them into a log file for later analysis, further processing or replay.

See [[Bag-play|bag-play]] for replaying and [[Bag-info|bag-info]] for inspection of log files.

h2. Obtaining @bag-record@

Binaries of the @bag-record@ program can be downloaded from the "continuous integration server":http://ci.cor-lab.org for versions 0.4 and 0.5 of the project:rsb:

* "0.4 Linux i686":https://ci.cor-lab.de/job/rsbag-tools-cl-0.4/label=ubuntu_lucid_32bit/ i686":https://ci.cor-lab.de/job/cl-rsbag-tools-stable/label=ubuntu_lucid_32bit/
* "0.4 Linux x86_64":https://ci.cor-lab.de/job/rsbag-tools-cl-0.4/label=ubuntu_lucid_64bit/ x86_64":https://ci.cor-lab.de/job/cl-rsbag-tools-stable/label=ubuntu_lucid_64bit/

* "0.5 Linux i686":https://ci.cor-lab.de/job/rsbag-tools-cl-0.5/label=ubuntu_lucid_32bit/ i686":https://ci.cor-lab.de/job/cl-rsbag-tools/label=ubuntu_lucid_32bit/
* "0.5 Linux x86_64":https://ci.cor-lab.de/job/rsbag-tools-cl-0.5/label=ubuntu_lucid_64bit/ x86_64":https://ci.cor-lab.de/job/cl-rsbag-tools/label=ubuntu_lucid_64bit/
* "0.5 MacOS x86_64":https://ci.cor-lab.de/job/rsbag-tools-cl-0.5/label=MAC_OS_lion_64bit/

* "trunk Linux i686":https://ci.cor-lab.de/job/rsbag-tools-cl/label=ubuntu_lucid_32bit/
* "trunk Linux x86_64":https://ci.cor-lab.de/job/rsbag-tools-cl/label=ubuntu_lucid_64bit/
* "trunk MacOS x86_64":https://ci.cor-lab.de/job/rsbag-tools-cl/label=MAC_OS_lion_64bit/ x86_64":https://ci.cor-lab.de/job/cl-rsbag-tools/label=MAC_OS_lion_64bit/

After the download, the @bag-record@ file has to be made executable in most cases. This can be done for example by executing
<pre>
chmod +x bag-record
</pre>
in the download directory.

h2. Checking Versions and Displaying Help

Version and help information is displayed when the @--version@ and @--help[-all]@ commandline options are specified:
<pre>
./bag-record --version
./bag-record --help
./bag-record --help-all
</pre>
The output of @--help[-all]@ includes a list of supported file formats.

h2. Recording Events

Some general remarks regarding recording of RSB events using @bag-record@:
* The specified output file into which events should be recorded, should not already exist
** If an empty file of the given name exists, it will be used for recording
** If a non-empty file of the given name exists, it will be extended as long as it does not already contain any of the channels being recorded
* The recording process can be terminated gracefully by sending one of @SIGINT@ and @SIGTERM@ to the @bag-record@ process

For details regarding the URI syntax involved in transport and channel specifications, see [[rsb:URI_Schema|URI Schema]].

h3. Recording from a Nao robot using a local Spread daemon

This example assumes
* A Spread daemon running on the local machine and listening on port 4803
* Image, Sound and Proprioception message are published (for example by running the "streaming components for Nao":https://code.humavips.eu/projects/naorsb/wiki/Components) on the RSB channels
** @/nao/vision/top@
** @/nao/audio/all@
** @/nao/proprioception@
* Image, Sound and Proprioception message are encoded using the project:rst data types
** rst:source:trunk/rst/proto/rst/ImageMessage.proto
** rst:source:trunk/rst/proto/rst/SoundMessage.proto
** rst:source:trunk/rst/proto/rst/ProprioceptionData.proto

<pre>
./bag-record -o /tmp/nao.tide
'spread:/nao/vision/top?name=4803'
'spread:/nao/audio/all?name=4803'
'spread:/nao/proprioception?name=4803'
</pre>

The resulting file will (unless a different channel allocation is specified) contain one channel for each of the three RSB channels.

*Note: the file extension ("tide" in this case) determines the used file format backend. Currently, only the "TIDELog":https://retf.info/svn/drafts/rd-0001.txt file format is supported.*

h3. Recording from a Nao robot using a remote Spread daemon

This example assumes
* A Spread daemon running on the machine "remote" and listening on port 4803
* Same data types as above

<pre>
./bag-record -o /tmp/nao.tide
'spread://remote:4803/nao/vision/top'
'spread://remote:4803/nao/audio/all'
'spread://remote:4803/nao/proprioception'
</pre>

h3. Remote-Controlling Recording

@bag-record@ can expose an RPC interface that allows starting, stopping and terminating the recording process. This feature is enabled using the @--control-uri@ (@-c@) commandline option. An URI has to be supplied as an argument of the option to configure the scope and transport through which the RPC interface should be exposed. The interface consists of three methods:

* @start : void -> void@
Restart recording after it has been stopped.
* @stop : void -> void@
Stop recording allowing it to be restarted later.
* @terminate : void -> void@
Terminate the recording process and the program.

Example
<pre>
./bag-record -c 'spread:/control' -o /tmp/everything.tide spread:
</pre>
Then, in parallel
<pre>
./call 'spread:/control/terminate()'
</pre>