====== IPAACA tools ======

===== General options =====


  * All IPAACA-tools/scripts provide a list of options – with some explanation – if called with the argument ''-h'', e.g., ''ipaaca-iu-injector -h''.

  * All tools/scripts also share the same basic RSB/IPAACA arguments.


===== ipaaca-iu-injector =====

''ipaaca-iu-injector'' is a command line tool with which single IPAACA IUs or message-type-IUs can be send. 

By default it sends message-type-IUs. This can be changed by specifying the argument ''-t IU'', in which case the injector idles for a certain amount of time (3s default, configurable with the argument ''-k SECONDS'', e.g., ''-k 10'') before it exits. This is important when a receiving component makes a change to the published IU.

The injector has a single non-optional argument (''-c CATEGORY'', e.g., ''-c testcat''), which specifies the category of the IU/Message that will be send. It is of course also possible to specify a payload, which is done with the argument ''-p KEY VALUE [KEY VALUE ...]'', i.e., a list of alternating payload keys and payload values. By default, KEY and VALUE are interpreted as Strings, e.g., ''-p Hallo Welt bis bald'' will result in a Payload object ''{'Hallo': 'Welt', 'bis': 'bald'}''. When specifying the argument ''-j'', the VALUE arguments will be interpreted to be Python expressions and need to be escaped as such. For the example above, we would thus need to specify it as follows: ''-p Hallo "'Welt'" bis "'bald'"''. The double quotes instruct the cmd shell (e.g., bash) that a string, which may also contain spaces and other special characters, will follow. The single quotes are Python syntax for string literals.

Using the ''-j'' arguments also allows the specification of non-string payload values, such as boolean values, numbers, lists or maps. In this case shell double quotes simply enclose the Python syntax for specifying the data type (which may of course be nested):

  * ''-p send-data "True"'' -> ''{'send-data': true}''
  * ''-p cmd "'set-streams'" streams "{'gaze': True, 'eyes': False}"'' -> ''{'cmd': 'set-streams', 'streams': {'gaze': true, 'eyes': false}}''
  * ''-p resolution "[1920, 1080]"'' -> ''{'resolution': [1920, 1080]}''
  * ''-p result "None"'' -> ''{'result': null}''


===== ipaaca-iu-sniffer =====

''ipaaca-iu-sniffer'' is a command line tool with which all (or a filtered subset) of the IPAACA IUs or message-type-IUs can be monitored.

By default it prints each IU/Message that is send on the channel "default". This can be changed by specifying a list of channels to monitor using the ''--channels CHANNEL [CHANNEL ...]'' argument, e.g., ''--channels billie vince''.

The IUs/Messages that are printed can be further limited in two ways:
  - By specifying the categories to listen to using the argument ''-c CATEGORY [CATEGORY ...]'' (where CATEGORY can also be a regular expression if the switch -r is given as an argument). Examples include:
    * ''-c asrresults'' -- Only listen to IUs/Messages of the category asrresults
    * ''-r -c "asr.*"'' -- Only listen to IUs/Messages of the categories with names that match the regular expression 'asr.', e.g., "asr", "asrresults", "asrcmds", …
    * ''-r -c '^(?!asr).*$''' -- Listen to any category _except_ those starting with "asr"
  - By specifying the event types to listen to using the argument ''-e EVENT-TYPE [EVENT-TYPE ...]'' (chosen from the set ''LINKSUPDATED UPDATED ADDED RETRACTED COMMITTED DELETED MESSAGE'').