The triggered publisher system publishes a user specified message on an output topic in response to an input message that matches user specified criteria. It can also call a user specified service as an output in response to an input message. It currently supports blocking service call. An optional simulation time delay can be used delay message publication. More...

#include <TriggeredPublisher.hh>

Public Member Functions
	TriggeredPublisher ()=default
	Constructor. More...

	~TriggeredPublisher () override
	Destructor. More...

void	Configure (const Entity &_entity, const std::shared_ptr< const sdf::Element > &_sdf, EntityComponentManager &_ecm, EventManager &_eventMgr) override
	Configure the system. More...

void	DoWork ()
	Thread that handles publishing output messages. More...

bool	MatchInput (const transport::ProtoMsg &_inputMsg)
	Helper function that calls Match on every InputMatcher available. More...

void	PreUpdate (const UpdateInfo &_info, EntityComponentManager &_ecm) override

Public Member Functions inherited from System
	System ()=default
	Constructor. More...

virtual	~System ()=default
	Destructor. More...

Additional Inherited Members
Public Types inherited from System
using	PriorityType = int32_t
	Signed integer type used for specifying priority of the execution order of PreUpdate and Update phases. More...

Static Public Attributes inherited from System
constexpr static PriorityType	kDefaultPriority = {0}
	Default priority value for execution order of the PreUpdate and Update phases. More...

constexpr static std::string_view	kPriorityElementName
	Name of the XML element from which the priority value will be parsed. More...

Detailed Description

The triggered publisher system publishes a user specified message on an output topic in response to an input message that matches user specified criteria. It can also call a user specified service as an output in response to an input message. It currently supports blocking service call. An optional simulation time delay can be used delay message publication.

System Parameters

<input>: The tag contains the input message type, topic and matcher information.
- Attributes:
  - type: Input message type (e.g. gz.msgs.Boolean)
  - topic: Input message topic name
<input><match>: Contains configuration for matchers. Multiple <match> tags are possible. An output message is triggered if all Matchers match.
- Attributes:
  - logic_type("positive" or "negative"): Specifies whether a comparison must succeed or fail in order to trigger an output message. A "positive" value triggers a match when a comparison succeeds. A "negative" value triggers a match when a comparson fails. The default value is "positive"
  - tol: Tolerance for floating point comparisons.
  - field: If specified, only this field inside the input message is compared for a match.
- Value: String used to construct the protobuf message against which input messages are matched. This is the human-readable representation of a protobuf message as used by gz topic for publishing messages
<output>: Contains configuration for output messages: Multiple <output> tags are possible. A message will be published on each output topic for each input that matches.
- Attributes:
  - type: Output message type (e.g. gz.msgs.Boolean)
  - topic: Output message topic name
- Value: String used to construct the output protobuf message . This is the human-readable representation of a protobuf message as used by gz topic for publishing messages
<delay_ms>: Integer number of milliseconds, in simulation time, to delay publication.
<service>: Contains configuration for service to call: Multiple <service> tags are possible. A service will be called for each input that matches.
- Attributes:
  - name: Service name (e.g. /world/triggered_publisher/set_pose)
  - timeout: Service timeout
  - reqType: Service request message type (e.g. gz.msgs.Pose)
  - repType: Service response message type (e.g. gz.msgs.Empty)
  - reqMsg: String used to construct the service protobuf message.

Examples

Any receipt of a Boolean messages on the input topic triggers an output
<plugin>

<input type="gz.msgs.Boolean" topic="/input_topic"/>

<output type="gz.msgs.Empty" topic="/output_topic"/>

</plugin>
Full match: An output is triggered when a Boolean message with a value of "true" is received
<plugin>

<input type="gz.msgs.Boolean" topic="/input_topic">

<match>

data: true

</match>

</input>

<output type="gz.msgs.Empty" topic="/output_topic"/>

</plugin>
Field match: An output is triggered when a specific field matches
<plugin>

<input type="gz.msgs.Vector2d" topic="/input_topic">

<match field="x">1.0</match>

<match field="y">2.0</match>

</input>

<output type="gz.msgs.Empty" topic="/output_topic"/>

</plugin>

The logic_type attribute can be used to negate a match. That is, to trigger an output when the input does not equal the value in <match> For example, the following will trigger an ouput when the input does not equal 1 AND does not equal 2.

<plugin>
  <input type="gz.msgs.Int32" topic="/input_topic">
    <match logic_type="negative">1</match>
    <match logic_type="negative">2</match>
  </input>
  <output type="gz.msgs.Empty" topic="/output_topic"/>
</plugin>

Repeated Fields

When a field matcher is used with repeated fields, the content of the repeated field is treated as a set and the comparison operator is set containment. For example, the data field of gz.msgs.Int32_V is a repeated Int32 message. To match an input that contains the values 1 and 2 the following matcher can be used:

<plugin>
  <input type="gz.msgs.Int32_V" topic="/input_topic">
    <match field="data">1</match>
    <match field="data">2</match>
  </input>
  <output type="gz.msgs.Empty" topic="/output_topic"/>
</plugin>

To match an Int32_V message with the exact contents {1, 2}, the full matcher is used instead

<plugin>
  <input type="gz.msgs.Int32_V" topic="/input_topic">
    <match>
       data: 1
       data: 2
    </match>
  </input>
  <output type="gz.msgs.Empty" topic="/output_topic"/>
</plugin>

Limitations

The current implementation of this system does not support specifying a subfield of a repeated field in the "field" attribute. i.e, if field="f1.f2", f1 cannot be a repeated field.

Constructor & Destructor Documentation

◆ TriggeredPublisher()

TriggeredPublisher ( )

default

Constructor.

◆ ~TriggeredPublisher()

~TriggeredPublisher ( )

override

Destructor.

Member Function Documentation

◆ Configure()

void Configure	(	const Entity &	_entity,
		const std::shared_ptr< const sdf::Element > &	_sdf,
		EntityComponentManager &	_ecm,
		EventManager &	_eventMgr
	)

overridevirtual

Configure the system.

Parameters

[in]	_entity	The entity this plugin is attached to.
[in]	_sdf	The SDF Element associated with this system plugin.
[in]	_ecm	The EntityComponentManager of the given simulation instance.
[in]	_eventMgr	The EventManager of the given simulation instance.

Implements ISystemConfigure.

◆ DoWork()

void DoWork ( )

Thread that handles publishing output messages.

◆ MatchInput()

bool MatchInput ( const transport::ProtoMsg & _inputMsg )

Helper function that calls Match on every InputMatcher available.

Parameters

[in] _inputMsg Input message

Returns: True if all of the matchers return true

◆ PreUpdate()

void PreUpdate	(	const UpdateInfo &	_info,
		EntityComponentManager &	_ecm
	)