API Documentation

Core

The Core API provides access to commonly used functions and data types for PolySync applications. This API defines a set of globally unique parameters and Diagnostic Trouble Codes (DTCs) that enable applications to communicate their runtime status. This API also provides the PolySync Core enumerations, types, and variables.

Usage #include <polysync_core.h>

Functions

void psync_log_message ( … )

This will log a formatted message with priority. It is recommended to prefer the priority specific logger macros:

psync_log_message ( LOG_LEVEL_WARN, “my message - val: %.2f”, 1.23 );

Parameters
In/Out Type Name Description
in const ps_log_level_kind level The log level/priority.
in const char * format A log string formatter.
in Additional arguments to format.

psync_init ( … )

This will create a PolySync node and initialize its resources. It establishes a node connection to the specified PolySync domain.

Parameters
In/Out Type Name Description
in const char * node_name A pointer to char that specifies the node name buffer.
in const ps_node_type node_type The node type to configure. Some values are not available under certain license models. The value PSYNC_NODE_TYPE_API_USER is the default.
in const unsigned long domain_id This is the domain the node will operate in. The value PSYNC_DEFAULT_DOMAIN is the default.
in const unsigned long sdf_key A node SDF key. The value PSYNC_SDF_ID_INVALID means that the node is not in the SDF.
in const unsigned long flags The node flags. A value of zero is the default.
out ps_node_ref * node_ref_ptr A pointer to ps_node_ref that receives the initialization.
Returns
  • DTC Code:
    • DTC_NONE - If success
    • DTC_USAGE - If argument is invalid
    • DTC_CONFIG - If node_ref is already initialized, or SDF 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

psync_release ( … )

This will release a PolySync node and its resources.

Parameters
In/Out Type Name Description
in ps_node_ref * node_ref_ptr A pointer to ps_node_ref that is released.
Returns

psync_get_logger_configuration_file_path ( … )

This will get the default logger configuration file path.

Parameters
In/Out Type Name Description
in ps_node_ref node_ref Reference to the node.
out char * const path A pointer to char destination that receives the fully qualified path.
in const unsigned long path_len Maximum size of path destination.
Returns

psync_set_logger_configuration_file_path ( … )

This will set the logger configuration file path and reload the logger.

Parameters
In/Out Type Name Description
in ps_node_ref node_ref Reference to the node.
in const char * const path A pointer to char destination that receives the fully qualified path.
Returns

psync_set_logger_category ( … )

This will set the logger category. The default category is 'polysync'.

Parameters
In/Out Type Name Description
in ps_node_ref node_ref Reference to the node.
in const char * const category A pointer to the new category name.
Returns

psync_set_logger_node_context ( … )

This will set the logger node context information. The thread that invokes psync_init will set (by default) the logger node context information. The default node context is 'node_name-node_guid'.

In/Out Type Name Description
in ps_node_ref node_ref Reference to the node.
Returns

psync_get_timestamp ( … )

This will get the current, synchronized timestamp in microseconds. The PolySync time domain uses UTC microsecond timestamps, unless otherwise specified.

Parameters
In/Out Type Name Description
out ps_timestamp * const timestamp A pointer to ps_timestamps that receives the system timestamp value. [UTC microseconds]
Returns

psync_get_monotonic_timestamp ( … )

This will get the current monotonic timestamp.

Parameters
In/Out Type Name Description
out ps_timestamp * const timestamp A pointer to the ps_timestamp that receives the system’s monotonic timestamp value. [UTC microseconds]
Returns

psync_sleep_micro ( … )

This will sleep for the given duration in microseconds.

Parameters
In/Out Type Name Description
in const ps_timestamp interval The amount of time to sleep for. [microseconds]
Returns

psync_check_license_feature ( … )

This will check if the node has the given licensed feature available.

Parameters
In/Out Type Name Description
in const ps_node_ref node_ref Reference to the node that contains the licensed feature set.
in const char * feature_name A pointer to char that specifies the null-terminated feature name buffer.
out unsigned int * const is_valid A pointer to unsigned int that is set to zero if the feature is not valid or available.
Returns

psync_is_license_valid ( )

This will check if the current license is valid.

Returns

psync_get_build_version ( … )

This will get the PolySync API build version information.

Parameters
In/Out Type Name Description
out unsigned int * const major Major version digit.
out unsigned int * const minor Minor version digit.
out unsigned int * const subminor Sub-minor version digit.
out unsigned long * const build_date Build date in UTC seconds.
Returns

psync_get_build_version_buffer ( … )

This will fill the buffer with major-minor-subminor-build_date.

Parameters
In/Out Type Name Description
out unsigned long long * const version_buffer A pointer to an unsigned long long that receives the build version data.
Returns

psync_get_file_hash ( … )

This will get the MD5 hash of a file.

Parameters
In/Out Type Name Description
in const char* file_path A pointer to the char buffer that specifies the file path.
out unsigned char * const name_buffer A pointer to the char buffer that receives the hash value.
in const size_t name_buffer_len The length of the provided name_buffer.
Returns

psync_interface_address_string_to_value ( … )

This will convert the interface address string to an unsigned long value. It will expect a format similar to “X.X.X.X”.

Example

In Out
"160.176.192.208" 0xA0B0C0D0
"AUTO" PSYNC_INTERFACE_ADDRESS_AUTO
Parameters
In/Out Type Name Description
in const char * address A pointer to a char buffer that specifies the address buffer.
out ps_interface_address * const value A pointer to ps_interface_address that specifies the address buffer.
Returns

psync_interface_address_value_to_string ( … )

This will convert the interface address unsigned long value to a string.

Example
In Out
0xA0B0C0D0 "160.176.192.208"
PSYNC_INTERFACE_ADDRESS_AUTO "AUTO"
Parameters
In/Out Type Name Description
in const ps_interface_address value The value to convert.
out char * const address A pointer to a char buffer that receives the address value.
in const size_t address_len The length of a provided address.
Returns

psync_get_module_info ( … )

This will query the data model for information on a given module by name. Standard modules:

  • Core
    • Contains core PolySync definitions
  • Navigation
  • Sensor
  • Control
Parameters
In/Out Type Name Description
in const ps_node_ref node_ref A node reference that contains the data model.
in const char* name A pointer to the char buffer that specifies the module name.
out unsigned int * const major A pointer to the unsigned int that receives the module major version.
out unsigned int * const minor A pointer to the unsigned int that receives the module minor version.
out unsigned int * const subminor A pointer to the unsigned int that receives the module subminor version.
out unsigned long * const build_date A pointer to the unsigned long that receives the module build date. [UTC seconds]
out unsigned char * const hash_buffer A pointer to the unsigned char buffer that receives the module MD5 hash.
Returns

psync_guid_get_node_id ( … )

This will extract the node ID from the GUID. The node identifier is a unique ID for the node, with respect to the PolySync data-bus domain.

Parameters
In/Out Type Name Description
in const ps_guid guid GUID to parse.
out ps_identifier * const node_id A pointer to ps_identifier that receives the node ID value.
Returns

psync_guid_get_sdf_id ( … )

This will extract the node SDF ID from a GUID.

Parameters
In/Out Type Name Description
in const ps_guid guid The GUID to parse.
out unsigned long * const id A pointer to an unsigned long that receives the node SDF ID value.
Returns

psync_guid_get_node_type ( … )

This will extract the node type from a GUID.

Parameters
In/Out Type Name Description
in const ps_guid guid The GUID to parse.
out ps_node_type * const node_type A pointer to ps_node_type that receives the node type value.
Returns

psync_guid_set_node_id ( … )

This will set the node identifier field in a GUID.

Parameters
In/Out Type Name Description
in const ps_identifier node_id The node identifier to be copied.
out ps_guid * const guid guid A pointer to the GUID that will have the node identifier value set.
Returns

psync_guid_set_sdf_id ( … )

This will set the node SDF identifier field in a GUID.

Parameters
In/Out Type Name Description
in const unsigned long sdf_id The SDF identifier value to be copied.
out ps_guid * const guid guid A pointer to the GUID that will have the node identifier value set.
Returns
  • DTC Code:
    • DTC_NONE - If success
    • DTC_USAGE - If arguments are invalid

psync_guid_set_node_type ( … )

This will set the node type field in a GUID.

Parameters
In/Out Type Name Description
in const ps_node_type node_type The node type value to be copied.
out ps_guid * const guid guid A pointer to the GUID that will have the node identifier value set.
Returns

Macros

PSYNC_INIT_FLAG_STDOUT_LOGGING

The initialization bit flag passed to psync_init.

Value Type Description
0x4 int Sets node behavior to echo messages logged via psync_log_message to stdout.

psync_log_debug ( … )

This is the macro wrapper of psync_log_message using LOG_LEVEL_DEBUG.

psync_log_info ( … )

This is the macro wrapper of psync_log_message using LOG_LEVEL_INFO.

psync_log_warn ( … )

This is the macro wrapper of psync_log_message using LOG_LEVEL_WARN.

psync_log_error ( … )

This is the macro wrapper of psync_log_message using LOG_LEVEL_ERROR.