API Documentation

Node

The Node API allows C++ applications to create a PolySync node. It’s built to handle publishing and subscribing to message types.

The Node class implements the PolySync node template, which is recommended for all runtime nodes to conform to.

This API provides the ability to query and set the node’s state and flags, set quality of service requirements for messages, and activate/recover from faults.

Usage #include <PolySyncNode.hpp>

Node

The Node class is a convenience class for creating a PolySync node. It is built to handle publishing and subscribing to message types.

Deprecated methods

deprecated alternative notes
Node::Node( int argc, char * argv[] ) Node::Node() Use setCommandLineOptions() (available in version PR8) prior to calling connectPolySync()
Node::getDomainID() Node::getDomainId() N/A
Node::getSDFID() Node::getSdfId() N/A
Node::getSubscriberReliabilityQOS() Node::getSubscriberReliabilityQos() N/A
Node::getPublisherReliabilityQOS() Node::getPublisherReliabilityQos() N/A
Node::isFaultActive() Node::faultIsActive() N/A
Node::setDomainID() Node::setDomainId() N/A
Node::setArgumentBuffer() Node::setCommandLineOptions() Use setCommandLineOptions() (available in version PR8) prior to calling connectPolySync()
Node::setArgumentCount() Node::setCommandLineOptions() Use setCommandLineOptions() (available in version PR8) prior to calling connectPolySync()
Node::setPublisherReliabilityQOS() Node::setPublisherReliabilityQos() N/A
Node::setSubscriberReliabilityQOS() Node::setSubscriberReliabilityQos() N/A
Node::getGUID() Node::getGuid() N/A
Node::setConfigurationEvent( int argc, char * argv[]) Node::setConfigurationEvent( const GetOpt & ) Use setCommandLineOptions() (available in version PR8) prior to calling connectPolySync()

Node::Node ( ) noexcept

The empty PolySync node constructor will create a node instance that allows the application to connect to the PolySync bus.

Once it is connected to the bus, the node can publish and subscribe to message types.

Parameters
in/out type name description
in int argc The number of strings in argv.
in char * argv An array of strings.

Node::~Node ( ) noexcept

This will stop the PolySync data flow. It will also call disconnectPolySync(), and block until releaseStateEvent() has been executed.

Node::activateFault ( … ) const

This will instruct PolySync to enter a fault state for this node.

Parameters
in/out type name description
in ps_dtc faultCode The fault code to activate.
in ps_node_state_kind newState The state to transition to as a result of the fault.
Returns
  • void
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::connectPolySync ( )

This will initialize the PolySync stateful execution loop of this node.

Returns
  • void
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - If node configuration is invalid
    • DTC_LICERR - If license does not exist, or does not allow the given configuration
    • DTC_PROTOCOL - If core/API versions do not match, or other nodes are on the domain with different data model versions
    • DTC_OSERR - If failed to initialize core resources
    • DTC_MEMERR - If failed to allocate core resources

Node::disconnectPolySync ( ) const noexcept

This will release this node from its execution loop in PolySync

Returns
  • void

virtual Node::errorStateEvent ( )

This will be continuously called while in ERROR state.

Reimplemented in SampleApplicationNode, ParameterGetSet, CANWriterNode, CANReaderNode, and PublisherSubscrberNode.

Returns
  • void

virtual Node::fatalStateEvent ( )

This will be called a single time after the node transitions into the FATAL state, but before terminating.

Reimplemented in SampleApplicationNode, ParameterGetSet, CANWriterNode, CANReaderNode, and PublisherSubscrberNode.

Returns
  • void

Node::faultIsActive( … ) const

Please check if the fault code is active.

Parameters
in/out type name description
ps_dtc faultToCheck Fault to check for.
Returns
  • bool - True if a fault is active
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::flagIsSet ( … ) const

Please check if the flag is enabled for this node.

Parameters
in/out type name description
in ps_node_flag_kind flag The flag to check within this nodes context.
Returns
  • bool - True if the flag is set for this node
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::getAvailableMessageCount ( ) const

This will get the number of message types that are available within this PolySync data model version.

Each message type is enumerated for every PolySync runtime.

Returns
  • ulong - Number of available message types for this node
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::getDomainId ( ) const noexcept

The default value is PSYNC_DEFAULT_DOMAIN.

Use setDomainId to change the domain.

Returns
  • unsigned long - Unique identifier for the node’s domain of operation

Node::getFlags ( ) const

Get the ulong value representing the bit field for all of the node’s flags.

Returns
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::getGuid ( ) const

This will get the unique PolySync bus domain identifier for this node.

Returns
  • ps_guid - Runtime ID for this node
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

std::string Node::getMessageNameByType ( … ) const

This will get the message name value by using its string type identifier.

Parameters
in/out type name description
in ps_msg_type msg_type The Message type identifier to lookup.
Returns
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::getMessageTypeByName ( … ) const

This will get the message type identifier value by using its string name.

Parameters
in/out type name description
in std::string type_name A string that specifies the name to lookup.
Returns
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

std::string Node::getNodeName ( ) const noexcept

This will get this node’s PolySync name.

Returns
  • std::string

Node::getNodeReference ( ) const noexcept

This will get the handle to a PolySync node returned by the API.

Returns

Node::getNodeType ( ) const noexcept

This will get the numeric, compile-time, and value for this node type.

Returns
  • ps_node_type - The API node type, i.e. hardware application, software algorithm, Studio, etc

Node::getPublisherReliabilityQos ( … ) const

This will get the reliability of published messages from this node.

Parameters
in/out type name description
in ps_msg_type messageType The message type to check for the quality of the publisher service.
Returns
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::getSdfId ( ) const noexcept

This will get the unique identifier for this node’s configuration from the System Design File (SDF).

Returns
  • Unique node identifier/key from the System Design File

Node::getState ( ) const

This will get this node’s current PolySync state.

Possible values: - NODE_STATE_AUTH - NODE_STATE_ERROR - NODE_STATE_FATAL - NODE_STATE_INIT - NODE_STATE_INVALID - NODE_STATE_OK - NODE_STATE_WARN

Returns
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::getSubscriberReliabilityQos ( … ) const

This will get the quality of service for a given message type on this node.

Parameters
in/out type name description
in ps_msg_type PolySync message type to check on quality of service for this node.
Returns
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::initializeFaultMachine ( ) const

This will create the node resources required to use the node template fault machine. This will place the node into NODE_STATE_INIT.

Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

virtual Node::initStateEvent ( )

This will get called once after the node transitions into the NODE_STATE_INIT.

Reimplemented in SampleApplicationNode, ParameterGetSet, PublisherSubscriberNode, DataGenerator, SocketReaderNode, SocketWriterNode, CANWriterNode, SerialReaderNode, SerialWriterNode, CANReaderNode, and HelloWorldSubscriberNode.

Returns
  • void

virtual Node::messageEvent ( … )

This will be called for every instance the provided message type is received from the PolySync bus.

The messageEvent is called regardless of what node populated the message.

Override this event in order to handle incoming PolySync messages. The default behavior is to do nothing.

Reimplemented in ParameterGetSet, PublisherSubscriberNode, HelloWorldSubscriberNode, and SampleApplicationNode.

Returns
  • void
Parameters
in/out type name description
in std::shared_ptr< Message > messageType The message containing PolySync data.

Node::messageTypeIsSupported ( … ) const noexcept

This will check if the node supports a given message type.

Parameters
in/out type name description
in ps_msg_type messageType The Message type identifier to lookup.
Returns
  • bool - Returns true if the message type is supported

virtual Node::okStateEvent ( )

This will be called continuously while the node is in the PolySync node OK state.

Reimplemented in ParameterGetSet, PublisherSubscriberNode, SocketReaderNode, SocketWriterNode, SampleApplicationNode, CANWriterNode, CANReaderNode, SerialReaderNode, SerialWriterNode, and DataGenerator.

Returns
  • void

Node::recoverFault ( … ) const

This will recover from the node’s fault state and transition to the provided node state.

Parameters
in/out type name description
in ps_dtc dtc The fault code to recover from.
in ps_node_state_kind nodeState The state to transition to as result of recovery from the fault.
Returns
  • void
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::registerListener ( … )

registerListener will set the messageEvent to listen for the supplied messageType.

The messageEvent is executed each time a message is received from the PolySync bus.

Parameters
in/out type name description
in ps_msg_type messageType The PolySync message type to register a listener for.
Returns
  • void
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::registerListenerToAllMessageTypes ( )

This will subscribe to each available message type in the PolySync data model.

The messageEvent will be executed for each message received from the PolySync bus.

This is typically used as a visualization tool. Only use this if the intention is to process all data in a single node.

Returns
  • void
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

virtual Node::releaseStateEvent ( )

This will be called once as the node exits.

CTRL+C will trigger the release state event prior to a different implementation in the developer’s subclass.

Reimplemented in SampleApplicationNode, ParameterGetSet, SocketReaderNode, SocketWriterNode, PublisherSubscriberNode, SerialWriterNode, and SerialReaderNode.

Returns
  • void

virtual setCommandLineOptions ( … )

Pass user input to the node connectPolySync().

Parameters
in/out type name description
in const GetOpt & commandLineOptions Packaged user input from the command line

#include <PolySyncNode.hpp>

int main( int argc, char * argv[] )
{
    polysync::Node myNode;

    myNode.setCommandLineOptions( { argc, argv } );

    myNode.connectPolySync();

    return 0;
 }

virtual Node::setConfigurationEvent ( … )

This will be called: - Once after the node transitions into the AUTH state and - Before entering the INIT state

This will happen near the start of the program, before any PolySync related operations.

To receive options for parsing, call setCommandLineOptions() prior to connectPolySync.

Reimplemented in SampleApplicationNode.

Parameters
in/out type name description
in const GetOpt & commandLineOptions Packaged user input from the command line
Returns
  • void

Node::setDefaultStateTimingInterval ( … ) noexcept

This is used to increase/decrease timing intervals for unused state event methods.

The default interval is 200000 [microseconds].

Parameters
in/out type name description
in ps_timestamp interval Unused state methods will sleep for this amount of time following each call.
Returns
  • void

Node::setDomainId ( … ) noexcept

Please call this before calling connectPolySync() to change the process domain for this node.

Otherwise, PSYNC_DEFAULT_DOMAIN is used.

Parameters
in/out type name description
in ulong domainId The domain ID for this node to operate under.
Returns
  • void

Node::setFlagOff ( … ) const

This will set the supplied node flag off for the given flag specifier.

Parameters
in/out type name description
in ps_node_flag_kind flag The flag kind that should be removed from the nodes flags.
Returns
  • void
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::setFlagOn ( … ) const

This will set the node flag to on for the given flag specifier.

Parameters
in/out type name description
in ps_node_flag_kind flag The flag kind that should be added to the node’s flags.
Returns
  • void
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::setFlags ( … )

This will enable disable flags with a bit field.

Parameters
in/out type name description
in ps_node_flags ps_node_flags Ulong represents the node’s bit-field.
Returns
  • void
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::setNodeName ( … ) noexcept

This will be used to set the name of this node, as seen by all PolySync nodes on the bus.

Please call this before calling connectPolySync(), otherwise the default node name is used: “API User Node.”

Parameters
in/out type name description
in std::string nodeName The string name of the node as seen by other PolySync nodes.
Returns
  • void

Node::setNodeType ( … ) noexcept

setNodeType will be used to set the node’s API type (i.e. hardware, software algorithm, Studio, etc.).

Please call this before calling connectPolySync(), otherwise the default value is used: PSYNC_NODE_TYPE_API_USER.

Parameters
in/out type name description
in ps_node_type nodeType The API type for this node, representing the type of processing this application performs.
Returns
  • void

Node::setOkStateTimingInterval ( … ) noexcept

If the application does not override the okStateEvent method, the timing interval can be adjusted to increase/decrease the rate at which the okStateEvent is called. Default interval is 200000 [microseconds].

Parameters
in/out type name description
in ps_timestamp interval Default amount of time that each call to okStateEvent will sleep following the function call. This is only applicable to implementations that have not overridden Node::okStateEvent.

Node::setPublisherReliabilityQos ( … )

This will set the node’s default publisher reliability QoS for a given message type.

Parameters
in/out type name description
in ps_msg_type Message type that the setting applies to.
in ps_reliability_qos_kind Reliability type.
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync
// Example - likely in @ref initStateEvent()

...

try
{
    setPublisherReliabilityQos(
        getMessageTypeByName(
            "ps_byte_array_msg" ), RELIABILITY_QOS_RELIABLE );
}
catch( polysync::DTCException & e )
{
    if( e.getDtc() == DTC_USAGE )
    {
        polySyncLogError( "This node is not yet initialized!" );
    }
}

Node::setSdfId ( … ) noexcept

Call this before calling connectPolySync() to link to an entry in the System Design File (SDF).

Otherwise, PSYNC_SDF_ID_INVALID is used.

Parameters
in/out type name description
in ulong sdfID
Returns
  • void

Node::setSubscriberReliabilityQos ( … )

This will set the node’s default subscriber reliability QoS for a given message type.

Parameters
in/out type name description
in ps_msg_type Message type that the setting applies to.
in ps_reliability_qos_kind Reliability type.
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::transitionState ( … ) const

This will manually transition a node from the current state to the supplied node state.

Parameters
in/out type name description
in ps_node_state_kind state The node state to transition to.
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync

Node::unregisterListener ( … ) const

This will remove the message event that is registered for the given message type.

Parameters
in/out type name description
in ps_msg_type type The message type to unregister the message event for.
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - This node is not yet known by PolySync
Retuns
  • void

virtual Node::warnStateEvent ( )

This will be called continuously while in the WARN state.

Reimplemented in SampleApplicationNode, ParameterGetSet, and PublisherSubscriberNode.

Retuns
  • void