xcore_api Introduction

This page lists the controller plugin APIs available for secondary development, organized by header under the SDK xcore_api/ directory.

The current header version is 0.0.3 (macro XCORE_API_VERSION in #include "version.hpp"). The interface package README.md states that it is based on controller v3.2.1. Ensure the xcore_api version used by the plugin matches the target controller version.

---

launch/launch_api.hpp

Header:	#include "launch/launch_api.hpp"

Macros

---

LAUNCH_MODULE(CLASS_NAME)

LAUNCH_MODULE registers the entry class with the controller. The default priority is 0.

CLASS_NAME is the entry class name. It must derive from LaunchAPI.

Notes

• The macro takes effect when the dynamic library is loaded. Internally it calls LaunchAPI::Register().
• If this macro or LAUNCH_MODULE_PRIORITY() is not used, the controller does not run the lifecycle functions of that entry class.

See also LAUNCH_MODULE_PRIORITY(), LaunchAPI, Controller Plugin Entry.

LAUNCH_MODULE_PRIORITY(CLASS_NAME, priority)

Registers the entry class with the given priority. A higher priority runs Init(), Start(), and Stop() earlier. The order among the same priority is not fixed.

See also LAUNCH_MODULE(), LaunchAPI::Register().

LaunchAPI Class

The LaunchAPI class is the abstract base class of all controller plugin entry modules.

Header:	#include "launch/launch_api.hpp"
Namespace:	xcore_api::launch

Public Functions

[pure virtual] void	Init()
[pure virtual] void	Start()
[pure virtual] void	Stop()
[static] bool	Register(int priority, std::shared_ptr<LaunchAPI> ptr)

Detailed Description

The LaunchAPI class is the controller plugin entry. A derived class must implement Init(), Start(), and Stop(), and register with LAUNCH_MODULE() or LAUNCH_MODULE_PRIORITY().

The controller calls them in this order: construct, Init() by priority, Start() by priority after every Init finishes, Stop() by priority on stop, then destroy. Construction and destruction order is not fixed. Release dependent resources in Stop().

#include "launch/launch_api.hpp"

class ExamplePlugin : public xcore_api::launch::LaunchAPI {
public:
    void Init() override {
        // Load configuration and initialize logs
    }

    void Start() override {
        // Register commands, services, Hooks, and log codes
    }

    void Stop() override {
        // Release resources, stop threads, and close the bus
    }
};

LAUNCH_MODULE(ExamplePlugin)

See also LAUNCH_MODULE(), Controller Plugin Entry.

Member Function Documentation

[pure virtual] void LaunchAPI::Init()

Initializes the plugin.

All entry modules run in priority order. Use this to load configuration, initialize logs, and prepare data structures.

See also Start(), InitLogAPI().

[pure virtual] void LaunchAPI::Start()

Called after every Init() has finished.

Use this to register RL commands, services, Hooks, and log codes, or start background tasks.

See also Init(), RegPluginCmdsAPI(), RegisterHooksAPI(), RegServiceAPI().

[pure virtual] void LaunchAPI::Stop()

Called when the controller stops or unloads the plugin.

Release resources, stop threads, and close device connections here.

See also Start().

[static] bool LaunchAPI::Register(int priority, std::shared_ptr<LaunchAPI> ptr)

Registers the entry module with the controller. A higher priority runs earlier. Returns true on success.

For secondary development, use LAUNCH_MODULE(). Do not call this directly.

See also LAUNCH_MODULE(), LAUNCH_MODULE_PRIORITY().

---

rl_cmd/morden_rl_cmd_api.hpp

Header:	#include "rl_cmd/morden_rl_cmd_api.hpp"

The spelling morden in the file name matches the SDK package.

Macros

BEGIN_COMMAND_API(cmd_config)

Builds an internal ModernRLCmdAPI builder from cmd_config. Use it together with PARAMS_API(), EXECUTE_API(), and REGISTER_COMMAND_API.

See also RLCmdConfigAPI, Command Registration.

PARAMS_API(...)

Sets the parameter checker for the current command. The arguments are one or more ArgTypeAPI values.

EXECUTE_API(lambda)

Sets the forward executor. The lambda type is RLCmdActionAPI.

EXECUTE_STB_API(lambda)

Sets the step-back executor. Use this when the step-back type is STEP_BACK_CUSTOM.

REGISTER_COMMAND_API

Registers the command built so far with the controller. Internally calls RegPluginCmdsAPI().

Call this from the entry module Start().

See also RegPluginCmdsAPI().

Enum Types

enum class xcore_api::rl_cmd::ValueTypeAPI

This enum type describes command argument types. The type must match the RL call site before you read an argument.

Constant	Description
ValueTypeAPI::VALUE_UNKNOWN	Unknown type
ValueTypeAPI::VALUE_INT	Integer
ValueTypeAPI::VALUE_DOUBLE	Floating point
ValueTypeAPI::VALUE_BOOL	Boolean
ValueTypeAPI::VALUE_STRING	String
ValueTypeAPI::VALUE_BYTE	Byte
ValueTypeAPI::VALUE_CLOCK	Clock
ValueTypeAPI::VALUE_CONFDATA	Configuration data
ValueTypeAPI::VALUE_FCBOXVOL / VALUE_FCCARTNUM / VALUE_FCCYLINDERVOL / VALUE_FCSPHEREVOL / VALUE_FCXYZNUM	Force-control related
ValueTypeAPI::VALUE_INTNUM	Integer array
ValueTypeAPI::VALUE_JOINTTARGET	Joint target
ValueTypeAPI::VALUE_LOAD	Load
ValueTypeAPI::VALUE_ORIENT	Orientation
ValueTypeAPI::VALUE_PATH	Path
ValueTypeAPI::VALUE_POS	Position
ValueTypeAPI::VALUE_POSE	Pose
ValueTypeAPI::VALUE_ROBTARGET	Cartesian point
ValueTypeAPI::VALUE_SPEED	Speed
ValueTypeAPI::VALUE_TOOL	Tool
ValueTypeAPI::VALUE_TRIGDATA	Trigger
ValueTypeAPI::VALUE_WOBJ	Work object
ValueTypeAPI::VALUE_ZONE	Zone
ValueTypeAPI::VALUE_SIGNAL_DI / VALUE_SIGNAL_DO / VALUE_SIGNAL_GI / VALUE_SIGNAL_GO / VALUE_SIGNAL_AI / VALUE_SIGNAL_AO	IO signal
ValueTypeAPI::VALUE_MODBUS	Modbus
ValueTypeAPI::VALUE_INPUT_SIGNAL	Input signal
ValueTypeAPI::VALUE_TRANS	Extra switch parameter, for example \Stop
ValueTypeAPI::VALUE_KEY_PARA	Keyword parameter
ValueTypeAPI::VALUE_SWITCH	On / Off
ValueTypeAPI::VALUE_TORQUE_INFO / VALUE_JOINT_TORQUE / VALUE_CART_TORQUE	Torque information
ValueTypeAPI::VALUE_SOCKET_SERVER / VALUE_SOCKET_CONNECT	Network control
ValueTypeAPI::VALUE_NULL	Null type

See also ArgTypeAPI, SymbolVarBaseAPI.

enum class xcore_api::rl_cmd::ArgRuleTypeAPI

This enum type describes default-argument rules.

Constant	Value	Description
ArgRuleTypeAPI::ARG_MUST_HAVE	0	Required
ArgRuleTypeAPI::ARG_DEFAULT_AT_LAST	1	Optional at the end of the argument list
ArgRuleTypeAPI::ARG_DEFAULT_NOT_LAST	2	Optional, not at the end of the argument list

enum xcore_api::rl_cmd::CommandProcessResultAPI

This enum type describes the command result returned by the inner executor.

Constant	Value	Description
CMD_PROCESS_SUCCESS	0	Success. RL continues
CMD_PROCESS_ERROR	1	Failure. Only the current task pauses
CMD_PROCESS_FATAL	2	Fatal error. RL stops
CMD_PROCESS_IGNORE	3	Async command. The task enters async wait
CMD_PROCESS_EXTRA	4	Extra executed command, often used for motion
CMD_PROCESS_RESCHEDULE	5	Request reschedule
CMD_PROCESS_SPECIAL	6	Special command. Affects scheduling

See also RLCmdActionAPI, SendCmd().

enum xcore_api::rl_cmd::CmdLookAheadImplAPI

This enum type describes command look-ahead behavior.

Constant	Value	Description
WAIT_MOVE_PAUSE	0	Wait for motion to finish and break look-ahead (default)
ACTIVATE_AT_LOOKAHEAD	1	Trigger at look-ahead, for example print-style commands
ACTIVATE_IN_ZONE	2	Trigger in the zone, after the previous motion
MOVEMENT_ITSELF	3	The motion command itself

Commands that involve motion must set look-ahead correctly so they do not break controller scheduling.

See also RLCmdConfigAPI::SetLookAhead(), Custom Motion Commands.

enum xcore_api::rl_cmd::TaskLimitAPI

This enum type describes the task limit of a command.

Constant	Value	Description
TASK_NO_LIMIT	0	No limit
TASK_LIMIT_MOVE	1	Limit motion tasks
TASK_LIMIT_NORMAL_AND_STATIC	2	Limit normal and semi-static tasks

enum xcore_api::rl_cmd::StepBackAPI

This enum type describes step-back behavior.

Constant	Value	Description
STEP_BACK_SKIP	0	Skip this command
STEP_BACK_STOP	1	Stop step-back
STEP_BACK_CUSTOM	2	Custom behavior with EXECUTE_STB_API()

Types

using xcore_api::rl_cmd::CommandExecuteAPI = std::function<CommandProcessResultAPI()>

Inner command executor. Returns CommandProcessResultAPI.

using xcore_api::rl_cmd::RLCmdActionAPI

Outer command factory. The signature is:

std::function<CommandExecuteAPI(
    std::shared_ptr<RLCallFrameAPI>,
    std::vector<std::shared_ptr<SymbolVarBaseAPI>>)>

The outer factory builds the inner CommandExecuteAPI at schedule time. The inner function runs the command logic.

See also RLCallFrameAPI, SymbolVarBaseAPI.

ArgTypeAPI Class

The ArgTypeAPI class describes the type, default rule, and default value of one command argument.

Header:	#include "rl_cmd/morden_rl_cmd_api.hpp"
Namespace:	xcore_api::rl_cmd

Public Functions

	ArgTypeAPI()
	ArgTypeAPI(ValueTypeAPI type)
	ArgTypeAPI(std::vector<ValueTypeAPI> types)
	ArgTypeAPI(ValueTypeAPI type, ArgRuleTypeAPI arg_rule, SymbolVarBaseAPI value)
	ArgTypeAPI(std::vector<ValueTypeAPI> types, ArgRuleTypeAPI arg_rule, SymbolVarBaseAPI value)
void	SetValueType(const ValueTypeAPI &type)
void	SetRule(const ArgRuleTypeAPI &rule)
void	SetDefaultValue(const SymbolVarBaseAPI &value)
std::vector<ValueTypeAPI>	GetValueType() const
ArgRuleTypeAPI	GetRule() const
std::shared_ptr<SymbolVarBaseAPI>	GetDefaultValue() const

Detailed Description

Required arguments are constructed with a single type or a type list. Optional arguments must also provide ArgRuleTypeAPI and a default value.

See also PARAMS_API(), ValueTypeAPI.

Member Function Documentation

void ArgTypeAPI::SetValueType(const ValueTypeAPI &type)

Sets the argument type.

void ArgTypeAPI::SetRule(const ArgRuleTypeAPI &rule)

Sets the default-argument rule.

void ArgTypeAPI::SetDefaultValue(const SymbolVarBaseAPI &value)

Sets the default value used when the argument is omitted.

std::vector<ValueTypeAPI> ArgTypeAPI::GetValueType() const

Returns the list of types this argument accepts.

ArgRuleTypeAPI ArgTypeAPI::GetRule() const

Returns the default-argument rule.

std::shared_ptr<SymbolVarBaseAPI> ArgTypeAPI::GetDefaultValue() const

Returns the default value.

RLCmdConfigAPI Class

The RLCmdConfigAPI class describes the name, look-ahead, task limit, and step-back behavior of one custom RL command.

Header:	#include "rl_cmd/morden_rl_cmd_api.hpp"
Namespace:	xcore_api::rl_cmd

Public Functions

	RLCmdConfigAPI()
	RLCmdConfigAPI(std::shared_ptr<RLCmdConfigImpl> ptr)
void	SetFuncName(const std::string &func_name)
void	SetLookAhead(const CmdLookAheadImplAPI &look_ahead)
void	SetTaskLimit(const TaskLimitAPI &limit)
void	SetStepBack(const StepBackAPI &step_type)
std::string	GetFuncName() const
CmdLookAheadImplAPI	GetLookAhead() const
TaskLimitAPI	GetTaskLimit() const
StepBackAPI	GetStepBack() const

Detailed Description

Fill in the configuration before BEGIN_COMMAND_API(). The default look-ahead is WAIT_MOVE_PAUSE. Motion commands must set look-ahead to MOVEMENT_ITSELF.

See also Command Registration, Custom Motion Commands.

Member Function Documentation

void RLCmdConfigAPI::SetFuncName(const std::string &func_name)

Sets the command function name. It must match the name used in RL.

void RLCmdConfigAPI::SetLookAhead(const CmdLookAheadImplAPI &look_ahead)

Sets the look-ahead mode. The default breaks look-ahead.

See also CmdLookAheadImplAPI.

void RLCmdConfigAPI::SetTaskLimit(const TaskLimitAPI &limit)

Sets the task limit.

void RLCmdConfigAPI::SetStepBack(const StepBackAPI &step_type)

Sets the step-back type.

std::string RLCmdConfigAPI::GetFuncName() const

Returns the command function name.

CmdLookAheadImplAPI RLCmdConfigAPI::GetLookAhead() const

Returns the look-ahead type.

TaskLimitAPI RLCmdConfigAPI::GetTaskLimit() const

Returns the task limit.

StepBackAPI RLCmdConfigAPI::GetStepBack() const

Returns the step-back behavior.

RLCallFrameAPI Class

The RLCallFrameAPI class provides the runtime context of the current command and can set a return value.

Header:	#include "rl_cmd/morden_rl_cmd_api.hpp"
Namespace:	xcore_api::rl_cmd

Public Functions

	RLCallFrameAPI(std::shared_ptr<RLCallFrameImpl> ptr)
std::string	GetCmdTask()
std::string	GetCmdFile()
int	GetCmdLine()
int	GetVisitedLine()
void	SetReturnValue(const SymbolVarBaseAPI &val)

Member Function Documentation

std::string RLCallFrameAPI::GetCmdTask()

Returns the current task name.

std::string RLCallFrameAPI::GetCmdFile()

Returns the current file name.

int RLCallFrameAPI::GetCmdLine()

Returns the current line number.

int RLCallFrameAPI::GetVisitedLine()

Returns the visited line number.

void RLCallFrameAPI::SetReturnValue(const SymbolVarBaseAPI &val)

Sets the command return value.

See also SymbolVarBaseAPI.

ModernRLCmdAPI Class

The ModernRLCmdAPI class is the custom-command builder. Secondary development usually uses the macros and does not instantiate this class directly.

Header:	#include "rl_cmd/morden_rl_cmd_api.hpp"
Namespace:	xcore_api::rl_cmd

Public Functions

explicit	ModernRLCmdAPI(const RLCmdConfigAPI &cfg)
virtual	~ModernRLCmdAPI()
RLCmdConfigAPI	GetCmdConfig()
const std::vector<std::shared_ptr<SymbolVarBaseAPI>> &	GetCmdArgs()
void	SetParams(const std::initializer_list<ArgTypeAPI> &v)
void	SetExecutor(RLCmdActionAPI &action)
void	SetExecutorStb(RLCmdActionAPI &action)
ModernRLCmdAPI	Convert()

Detailed Description

The BEGIN_COMMAND_API() macro constructs this object. PARAMS_API(), EXECUTE_API(), EXECUTE_STB_API(), and REGISTER_COMMAND_API call SetParams(), SetExecutor(), SetExecutorStb(), and RegPluginCmdsAPI() respectively.

Do not block for a long time in a command executor. Use the thread pool for long-running work.

See also Command Registration.

Member Function Documentation

RLCmdConfigAPI ModernRLCmdAPI::GetCmdConfig()

Returns the current command configuration.

const std::vector<std::shared_ptr<SymbolVarBaseAPI>> &ModernRLCmdAPI::GetCmdArgs()

Returns the current command argument symbol table.

void ModernRLCmdAPI::SetParams(const std::initializer_list<ArgTypeAPI> &v)

Sets the parameter checker. Use PARAMS_API().

void ModernRLCmdAPI::SetExecutor(RLCmdActionAPI &action)

Sets the forward executor. Use EXECUTE_API().

void ModernRLCmdAPI::SetExecutorStb(RLCmdActionAPI &action)

Sets the step-back executor. Use EXECUTE_STB_API().

ModernRLCmdAPI ModernRLCmdAPI::Convert()

Converts this object into a registerable command. Called by REGISTER_COMMAND_API.

SymbolVarBaseAPI Class

The SymbolVarBaseAPI class reads and writes the concrete value of a command argument.

Header:	#include "rl_cmd/morden_rl_cmd_api.hpp"
Namespace:	xcore_api::rl_cmd

Public Functions

	SymbolVarBaseAPI()
	SymbolVarBaseAPI(std::shared_ptr<SymbolVarBaseImpl> ptr)
SymbolVarBaseAPI	GetSubUnit(const std::string &key)
double	GetDoubleVal()
bool	GetBoolVal()
int	GetIntVal()
unsigned char	GetByteVal()
std::string	GetStringVal()
PointAPI	GetPointAPI()
SpeedAPI	GetSpeedAPI()
ZoneAPI	GetZoneAPI()
ToolAPI	GetToolAPI()
WobjAPI	GetWobjAPI()
void	ResetRobTarget(const PointAPI &point)
void	ResetBool(bool val)
void	ResetInt(int val)
void	ResetDouble(double val)
void	ResetString(const std::string &val)
void	ResetBoolArr(const std::vector<bool> &v)
void	ResetIntArr(const std::vector<int> &v)
void	ResetDoubleArr(const std::vector<double> &v)
void	ResetStringArr(const std::vector<std::string> &v)

Detailed Description

Confirm the argument type before reading. For composite values (for example a quaternion inside a Cartesian point), enter the child field with GetSubUnit(). When the type does not match, the basic readers return 0 / false / an empty string.

See also ValueTypeAPI, PointAPI.

Member Function Documentation

SymbolVarBaseAPI SymbolVarBaseAPI::GetSubUnit(const std::string &key)

Reads a child unit of a composite value by key.

double SymbolVarBaseAPI::GetDoubleVal()

Returns a double. Returns 0 when the type does not match.

bool SymbolVarBaseAPI::GetBoolVal()

Returns a bool.

int SymbolVarBaseAPI::GetIntVal()

Returns an int.

unsigned char SymbolVarBaseAPI::GetByteVal()

Returns the byte value.

std::string SymbolVarBaseAPI::GetStringVal()

Returns the string.

PointAPI SymbolVarBaseAPI::GetPointAPI()

Returns the point.

See also PointAPI.

SpeedAPI SymbolVarBaseAPI::GetSpeedAPI()

Returns the speed.

ZoneAPI SymbolVarBaseAPI::GetZoneAPI()

Returns the zone.

ToolAPI SymbolVarBaseAPI::GetToolAPI()

Returns the tool.

WobjAPI SymbolVarBaseAPI::GetWobjAPI()

Returns the work object.

void SymbolVarBaseAPI::ResetRobTarget(const PointAPI &point)

Writes the robtarget argument as point.

void SymbolVarBaseAPI::ResetBool(bool val)

Writes the Boolean argument as val.

void SymbolVarBaseAPI::ResetInt(int val)

Writes the integer argument as val.

void SymbolVarBaseAPI::ResetDouble(double val)

Writes the floating-point argument as val.

void SymbolVarBaseAPI::ResetString(const std::string &val)

Writes the string argument as val.

void SymbolVarBaseAPI::ResetBoolArr(const std::vector<bool> &v)

Overwrites the Boolean array. The length must match.

void SymbolVarBaseAPI::ResetIntArr(const std::vector<int> &v)

Overwrites the integer array.

void SymbolVarBaseAPI::ResetDoubleArr(const std::vector<double> &v)

Overwrites the floating-point array.

void SymbolVarBaseAPI::ResetStringArr(const std::vector<std::string> &v)

Overwrites the string array.

Related Non-Members

std::shared_ptr<RLCmdArgImpl> xcore_api::rl_cmd::RequireArgsAPI(const std::vector<ArgTypeAPI> &v)

Builds a command-argument object from a type list. Secondary development usually uses PARAMS_API() and does not call this directly.

bool xcore_api::rl_cmd::RegPluginCmdsAPI(std::shared_ptr<ModernRLCmdAPI> ptr)

Registers the command with the controller. Returns true on success. For secondary development, use REGISTER_COMMAND_API.

See also REGISTER_COMMAND_API.

---

motion_cmd/motion_cmd_api.hpp

Header:	#include "motion_cmd/motion_cmd_api.hpp"

Usually used with a custom RL command: parse arguments into MotionCmdArgsAPI, then enqueue them with MotionCmdAPI.

Enum Types

enum xcore_api::motion_cmd::MoveTypeAPI

This enum type describes the motion type.

Constant	Value	Description
MOVE_ABSJ	0	Absolute joint motion
MOVE_J	1	Joint motion
MOVE_L	2	Linear motion
MOVE_C	3	Circular motion
MOVE_CF	4	Full-circle motion. Call SetMoveCFData()
MOVE_T	5	Trochoid motion. Call SetMoveTData()
MOVE_SP	6	Spiral motion. Call SetMoveSPData()

enum xcore_api::motion_cmd::RotTypeAPI

This enum type describes the orientation rotation mode of a full-circle motion.

Constant	Description
CONST_POSE	Keep orientation
ROT_AXIS	Rotating-axis rotation
FIXED_AXIS	Fixed-axis rotation

enum xcore_api::motion_cmd::CallBackTypeAPI

This enum type describes the motion callback type.

Constant	Value	Description
MOVE_START	0	Motion start
MOVE_PAUSE	1	Motion pause
MOVE_FINISH	2	Motion finish
MOVE_ERROR	3	Motion error

See also MotionCmdArgsAPI::SetCallback().

MotionCmdArgsAPI Class

The MotionCmdArgsAPI class describes the target, type, tool, work object, speed, zone, triggers, and callbacks of one motion command.

Header:	#include "motion_cmd/motion_cmd_api.hpp"
Namespace:	xcore_api::motion_cmd

Public Functions

	MotionCmdArgsAPI()
virtual	~MotionCmdArgsAPI()
int	SetTargetPoint(const PointAPI &point)
int	SetMoveType(const MoveTypeAPI &type)
int	SetMoveCFData(RotTypeAPI type, double rundeg)
int	SetMoveTData(double radius, double step)
int	SetMoveSPData(double radius, double step, double angle, bool clockwise)
int	SetTool(const ToolAPI &tool)
int	SetWobj(const WobjAPI &wobj)
int	SetZone(const ZoneAPI &zone)
int	SetSpeed(const SpeedAPI &speed)
int	SetLast(bool last)
int	SetUpdatePointer(const std::string &task_name, const std::string &file_name, int line)
int	SetCallback(CallBackTypeAPI type, const std::function<void()> &func)
int	SetAuxPoint(const PointAPI &point)
int	SetTriggers(const std::vector<TriggerAPI> &triggers)
int	SetFinishInAdvance(double distance = 0.002)

Detailed Description

Pose, speed, and distance use SI units: position in meters, angles usually in radians. Unless noted otherwise, members return 0 on success.

Do not block for a long time in a callback or Trigger.

See also MotionCmdAPI, Custom Motion Commands, PointAPI.

Member Function Documentation

int MotionCmdArgsAPI::SetTargetPoint(const PointAPI &point)

Sets the target point. Returns 0 on success.

int MotionCmdArgsAPI::SetMoveType(const MoveTypeAPI &type)

Sets the motion type.

See also MoveTypeAPI.

int MotionCmdArgsAPI::SetMoveCFData(RotTypeAPI type, double rundeg)

Sets extra parameters for a full circle. Use this with MOVE_CF. rundeg is the execution angle, from -359 to 3600 degrees.

int MotionCmdArgsAPI::SetMoveTData(double radius, double step)

Sets extra parameters for a trochoid. Use this with MOVE_T. radius and step are in meters.

int MotionCmdArgsAPI::SetMoveSPData(double radius, double step, double angle, bool clockwise)

Sets extra parameters for a spiral. Use this with MOVE_SP. radius is in meters, step is in m/rad, and angle is in radians. clockwise is true for clockwise.

int MotionCmdArgsAPI::SetTool(const ToolAPI &tool)

Sets the tool.

int MotionCmdArgsAPI::SetWobj(const WobjAPI &wobj)

Sets the work object.

int MotionCmdArgsAPI::SetZone(const ZoneAPI &zone)

Sets the zone.

int MotionCmdArgsAPI::SetSpeed(const SpeedAPI &speed)

Sets the speed.

int MotionCmdArgsAPI::SetLast(bool last)

Marks this command as the last of a continuous motion. When last is true, the current continuous motion ends.

int MotionCmdArgsAPI::SetUpdatePointer(const std::string &task_name, const std::string &file_name, int line)

Updates the client execution pointer. The task, file, and line can be taken from RLCallFrameAPI.

int MotionCmdArgsAPI::SetCallback(CallBackTypeAPI type, const std::function &func)

Sets the callback for motion start, pause, finish, or error.

See also CallBackTypeAPI.

int MotionCmdArgsAPI::SetAuxPoint(const PointAPI &point)

Sets the auxiliary point. Multi-point motions such as arcs use this.

int MotionCmdArgsAPI::SetTriggers(const std::vector<TriggerAPI> &triggers)

Sets path triggers. MOVE_ABSJ does not support this.

See also TriggerAPI.

int MotionCmdArgsAPI::SetFinishInAdvance(double distance = 0.002)

Finishes this path early. Combine this with a Trigger or IO for search-style commands. distance is the maximum stop distance in meters. The default is 2 mm.

MotionCmdAPI Class

The MotionCmdAPI class sends motion parameters to the controller motion queue.

Header:	#include "motion_cmd/motion_cmd_api.hpp"
Namespace:	xcore_api::motion_cmd

Public Functions

	MotionCmdAPI()
virtual	~MotionCmdAPI()
int	SendCmd(const MotionCmdArgsAPI &args)
int	SendSegmentCmds(const std::vector<MotionCmdArgsAPI> &vargs)
int	SendStepBackCmd(const MotionCmdArgsAPI &args)

Detailed Description

Confirm the controller mode, task space, and robot busy state before sending. Returns 0 on success. The RL result of a motion command is usually CMD_PROCESS_EXTRA.

Warning: This changes the robot motion state.

See also StatesAPI, Custom Motion Commands.

Member Function Documentation

int MotionCmdAPI::SendCmd(const MotionCmdArgsAPI &args)

Sends one motion command. Returns 0 on success.

See also SendSegmentCmds().

int MotionCmdAPI::SendSegmentCmds(const std::vector<MotionCmdArgsAPI> &vargs)

Sends multiple interrupted continuous motions. Each segment pauses after it finishes, then the next starts. The next segment starts only after the previous one has finished.

Use this when one RL command contains multiple path segments.

See also SendCmd().

int MotionCmdAPI::SendStepBackCmd(const MotionCmdArgsAPI &args)

Builds and sends a step-back command.

---

sdk/sdk_cmd_api.hpp

Header:	#include "sdk/sdk_cmd_api.hpp"

Enum Types

enum class xcore_api::sdk_cmd::Status

This enum type describes the execution status of a non-motion SDK command.

Constant	Description
Status::SUCCESS	Command finished
Status::PENDING	Running
Status::ERROR	Execution error. The command reports it itself

SDKCmdAPI Class

The SDKCmdAPI class is the base class of non-motion commands that can enter the SDK command queue.

Header:	#include "sdk/sdk_cmd_api.hpp"
Namespace:	xcore_api::sdk_cmd

Public Functions

	SDKCmdAPI()
virtual	~SDKCmdAPI()
[virtual] void	BeforeProcess()
[pure virtual] Status	DerivedProcess()
[virtual] void	AfterProcess()

Detailed Description

A derived class must implement DerivedProcess(). It may override the before and after callbacks. Enqueue the command with MordenSDKCmdAPI::SendSDKCmd().

Member Function Documentation

[virtual] void SDKCmdAPI::BeforeProcess()

Callback before the command runs. The default implementation is empty.

[pure virtual] Status SDKCmdAPI::DerivedProcess()

Core command logic. Returns Status.

[virtual] void SDKCmdAPI::AfterProcess()

Callback after the command runs. The default implementation is empty.

MordenSDKCmdAPI Class

The MordenSDKCmdAPI class sends motion or non-motion commands into the SDK command queue. The spelling Morden in the class name matches the header.

Header:	#include "sdk/sdk_cmd_api.hpp"
Namespace:	xcore_api::sdk_cmd

Public Functions

	MordenSDKCmdAPI()
virtual	~MordenSDKCmdAPI()
int	SendSDKMotionCmd(const MotionCmdArgsAPI &args, int cmd_id)
int	SendSDKCmd(std::shared_ptr<SDKCmdAPI> ptr, int cmd_id)
void	SetFinalSDKCmd()

Member Function Documentation

int MordenSDKCmdAPI::SendSDKMotionCmd(const MotionCmdArgsAPI &args, int cmd_id)

Sends one SDK motion command. cmd_id is the command identifier. Returns 0 on success.

See also MotionCmdArgsAPI.

int MordenSDKCmdAPI::SendSDKCmd(std::shared_ptr<SDKCmdAPI> ptr, int cmd_id)

Sends one ordinary SDK command. Returns 0 on success.

See also SDKCmdAPI.

void MordenSDKCmdAPI::SetFinalSDKCmd()

Sets the command that breaks look-ahead.

---

hooks/

Corresponds to #include "hooks/hooks_api.hpp" and #include "hooks/hooks_args_api.hpp". After a plugin registers a Hook, the controller calls it when the matching event occurs. See hooks Module.

Header:	#include "hooks/hooks_api.hpp", #include "hooks/hooks_args_api.hpp"

Enum Types

enum xcore_api::hooks::HookEventAPI

This enum type describes the controller events that can be registered.

Constant	Description
INVALID_EVENT	Invalid event
POINT_CHANGE	Point create, delete, or modify
PP_TO_MAIN	Program pointer jumps to the main program
PP_TO_LINE	Program pointer jumps to a given line
B_START_RUN	Start running
B_PAUSE_RUN	Pause running
E_STOP_RUN	Emergency stop

enum xcore_api::hooks::RunTypeAPI

This enum type describes how a Hook callback runs.

Constant	Description
SYNC_RUN	Synchronous. Blocks the matching controller event
ASYNC_RUN_IN_THREAD_POOL	Asynchronous in the ordinary thread pool
ASYNC_RUN_IN_RT_THREAD	Runs on a real-time thread

Do not do long-running work in a synchronous Hook.

enum xcore_api::hooks::CURDAPI

This enum type describes a point-change operation.

Constant	Description
CREATE	Create
UPDATE	Update
READ	Read
DELETE	Delete

Types

using xcore_api::hooks::FUNC = std::function<void(const std::shared_ptr<const HookArgsBaseAPI>)>

Hook callback type. For events with arguments, dynamically cast the argument to the matching derived type, for example HookPPToLineArgsAPI.

HookDataAPI Class

The HookDataAPI class describes the event, callback, run type, and priority to register.

Header:	#include "hooks/hooks_api.hpp"
Namespace:	xcore_api::hooks

Public Functions

	HookDataAPI()
virtual	~HookDataAPI()
bool	SetEvent(HookEventAPI event)
bool	SetHook(const FUNC &hook)
bool	SetRunType(RunTypeAPI type)
bool	SetPriority(int pri)
const HookEventAPI	GetEvent() const
const FUNC	GetHook() const
const RunTypeAPI	GetRunType() const
const int	GetPriority() const

Detailed Description

Registration flow: construct HookDataAPI, call SetEvent() and SetHook(), optionally SetRunType() and SetPriority(), then call RegisterHooksAPI().

Notes

• RegisterHooksAPI() does not accept dynamic registration after plugin Start().
• UnRegisterHooksAPI() takes effect only after every plugin has finished Start.

See also RegisterHooksAPI(), hooks Module.

Member Function Documentation

bool HookDataAPI::SetEvent(HookEventAPI event)

Sets the event type. Returns true on success.

bool HookDataAPI::SetHook(const FUNC &hook)

Sets the callback. Returns true on success.

bool HookDataAPI::SetRunType(RunTypeAPI type)

Sets synchronous or asynchronous execution. Returns true on success.

bool HookDataAPI::SetPriority(int pri)

Sets the schedule priority. A higher value is scheduled earlier. Returns true on success.

const HookEventAPI HookDataAPI::GetEvent() const

Returns the configured event.

const FUNC HookDataAPI::GetHook() const

Returns the callback.

const RunTypeAPI HookDataAPI::GetRunType() const

Returns the run type.

const int HookDataAPI::GetPriority() const

Returns the priority.

HookArgsBaseAPI Class

The HookArgsBaseAPI class is the base class of all Hook arguments.

Header:	#include "hooks/hooks_args_api.hpp"
Namespace:	xcore_api::hooks

It has no business members. Events with arguments are cast in the callback to HookPointArgsAPI or HookPPToLineArgsAPI.

HookPointArgsAPI Class

The HookPointArgsAPI class describes the point name and create/update/delete operation of POINT_CHANGE.

Header:	#include "hooks/hooks_args_api.hpp"
Inherits:	HookArgsBaseAPI

Public Functions

	HookPointArgsAPI()
const std::string	GetPointName() const
bool	SetPointName(const std::string &name)
const CURDAPI	GetOperate() const
bool	SetOperate(const CURDAPI &operate)

Member Function Documentation

const std::string HookPointArgsAPI::GetPointName() const

Returns the point name.

bool HookPointArgsAPI::SetPointName(const std::string &name)

Sets the point name. Returns true on success.

const CURDAPI HookPointArgsAPI::GetOperate() const

Returns the create / delete / update operation.

bool HookPointArgsAPI::SetOperate(const CURDAPI &operate)

Sets the operation type. Returns true on success.

HookPPToLineArgsAPI Class

The HookPPToLineArgsAPI class describes the task, file, and line of PP_TO_LINE.

Header:	#include "hooks/hooks_args_api.hpp"
Inherits:	HookArgsBaseAPI

Public Functions

	HookPPToLineArgsAPI()
const std::string	GetFileName() const
bool	SetFileName(const std::string &name)
const int	GetFileLine() const
bool	SetFileLine(const int line)
const std::string	GetTaskName() const
bool	SetTaskName(const std::string &name)

Member Function Documentation

const std::string HookPPToLineArgsAPI::GetFileName() const

Returns the jump-target file name.

bool HookPPToLineArgsAPI::SetFileName(const std::string &name)

Sets the file name. Returns true on success.

const int HookPPToLineArgsAPI::GetFileLine() const

Returns the jump-target line.

bool HookPPToLineArgsAPI::SetFileLine(const int line)

Sets the line number. Returns true on success.

const std::string HookPPToLineArgsAPI::GetTaskName() const

Returns the task name.

bool HookPPToLineArgsAPI::SetTaskName(const std::string &name)

Sets the task name. Returns true on success.

Related Non-Members

int xcore_api::hooks::RegisterHooksAPI(const HookDataAPI &data)

Registers the Hook with the controller. A return value greater than 0 is the hook id and means success. -1 means failure.

Does not accept dynamic registration after plugin Start().

See also UnRegisterHooksAPI(), HookDataAPI.

int xcore_api::hooks::UnRegisterHooksAPI(int hook_id)

Removes a registered Hook by hook_id. Call this only after every plugin has finished Start. Returns 0 on success.

See also RegisterHooksAPI().

---

states/states_api.hpp

Header:	#include "states/states_api.hpp"

Enum Types

enum xcore_api::states::TaskSpaceAPI

This enum type describes task-space occupancy.

Constant	Description
TS_READY	Idle
TS_BUSY	Busy

enum xcore_api::states::RunningStateAPI

This enum type describes the current robot invocation stage.

Constant	Value	Description
RS_NONE	0	None
RS_START	1	Start
RS_PAUSE	2	Pause
RS_STEP	3	Step
RS_BACK	4	Step back
RS_ERROR_HANDLER	5	Error handling
RS_RESET	6	Reset
RS_COLLISION	7	Collision
RS_STOP_EVENT	8	Emergency stop
RS_NUM_NEVER_USE	9	Sentinel. Do not use

StatesAPI Class

The StatesAPI class queries or sets controller runtime state.

Header:	#include "states/states_api.hpp"
Namespace:	xcore_api::states

Public Functions

	StatesAPI()
virtual	~StatesAPI()
bool	IsAutoMode()
bool	SetAutoMode(bool mode)
bool	IsPowerOn()
bool	SetPowerOn(bool on)
bool	IsTaskSpaceReady()
int	SetTaskSpace(const TaskSpaceAPI &space, bool busy)
bool	IsRobotBusy()
bool	SetRobotBusy(bool busy)
RunningStateAPI	GetRunningState()
bool	IsSimuMode()

Detailed Description

Confirm the current mode and task state before changing controller state. When combining this with motion or task control, first check whether the action is allowed.

SetRobotBusy() and SetTaskSpace() must occupy and release in pairs. Otherwise other modules may be blocked from using the robot.

See also RLTaskAPI, MotionCmdAPI.

Member Function Documentation

bool StatesAPI::IsAutoMode()

Returns whether the controller is in auto mode. true is auto, false is manual.

See also SetAutoMode().

bool StatesAPI::SetAutoMode(bool mode)

Sets auto / manual mode. mode true selects auto. Returns true on success.

Warning: This changes the controller operating mode.

See also IsAutoMode().

bool StatesAPI::IsPowerOn()

Returns whether the controller is powered on.

See also SetPowerOn().

bool StatesAPI::SetPowerOn(bool on)

Sets power on / off. on true powers on. Returns true on success.

Warning: This changes the controller power state.

See also IsPowerOn().

bool StatesAPI::IsTaskSpaceReady()

Returns whether the task space is idle and available.

See also SetTaskSpace().

int StatesAPI::SetTaskSpace(const TaskSpaceAPI &space, bool busy)

Sets task-space occupancy. Occupies when space is TS_BUSY and busy is true. Releases and returns to Ready when busy is false. Returns 0 on success.

See also IsTaskSpaceReady(), TaskSpaceAPI.

bool StatesAPI::IsRobotBusy()

Returns whether the robot is occupied. true means busy and unavailable.

See also SetRobotBusy().

bool StatesAPI::SetRobotBusy(bool busy)

Sets the robot busy / idle. Use this in pairs. Returns true on success.

See also IsRobotBusy().

RunningStateAPI StatesAPI::GetRunningState()

Returns the current running stage.

See also RunningStateAPI.

bool StatesAPI::IsSimuMode()

Returns whether the controller is in simulation. true is simulation, false is a real robot.

---

rl_task/rl_task_api.hpp

Header:	#include "rl_task/rl_task_api.hpp"

RLTaskAPI Class

The RLTaskAPI class controls and queries RL program tasks.

Header:	#include "rl_task/rl_task_api.hpp"
Namespace:	xcore_api::rl_task

Public Functions

	RLTaskAPI()
virtual	~RLTaskAPI()
bool	PPToMain()
bool	IsProgramResetDone()
bool	PPToLine(const int line, const std::string &task_name = "", const std::string &file_name = "")
bool	PPToFunc(const int line, const std::string &task_name = "", const std::string &file_name = "")
bool	ModifyProgramLoop(bool prog_loop)
bool	AlarmRLTask(const std::string &name)
bool	StartRun()
bool	PauseRun()
bool	PauseRunAndWaitIdle(int timeout_ms = 2000)
bool	PauseTask(const std::string &task_name)
bool	StopRun()
std::pair<std::string, int>	GetPointedLine(const std::string &task_name = "")
std::pair<std::string, int>	GetExecLine(const std::string &task_name = "")
int	SetPointedLine(const std::string &task_name, const std::string &file_name, int line)
int	SetExecLine(const std::string &task_name, const std::string &file_name, int line)
bool	IsTaskExists(const std::string &name)
bool	IsTaskRunning(const std::string &task_name)
bool	IsTaskRunning()

Detailed Description

If a jump fails, the interpreter state may become uncontrolled. Reload the task if needed. Pointer line numbers may be off by 1.

Warning: StopRun() deletes the task. After stop, reload the task before running again.

Member Function Documentation

bool RLTaskAPI::PPToMain()

Resets the program pointer to the main program. Returns true on success.

See also IsProgramResetDone().

bool RLTaskAPI::IsProgramResetDone()

Returns whether program reset has finished.

bool RLTaskAPI::PPToLine(const int line, const std::string &task_name = "", const std::string &file_name = "")

Jumps to the given task, file, and line. When both task_name and file_name are empty, single-task mode jumps to line in the currently executing file.

If the jump fails, the state is uncontrolled. Reload the task.

See also PPToFunc(), PPToMain().

bool RLTaskAPI::PPToFunc(const int line, const std::string &task_name = "", const std::string &file_name = "")

Jumps to the given function, mainly for debugging. When the last two arguments are empty, single-task mode jumps to a function in the currently executing file.

If the jump fails, the interpreter state is uncontrolled. Reload the task.

bool RLTaskAPI::ModifyProgramLoop(bool prog_loop)

Changes the loop mode. prog_loop true runs in a loop.

bool RLTaskAPI::AlarmRLTask(const std::string &name)

Wakes the task named name. Returns true on success.

bool RLTaskAPI::StartRun()

Starts program execution. Returns true on success.

See also PauseRun(), StopRun().

bool RLTaskAPI::PauseRun()

Pauses RL. It can be started again later. Returns true on success.

See also StartRun(), PauseRunAndWaitIdle().

bool RLTaskAPI::PauseRunAndWaitIdle(int timeout_ms = 2000)

Pauses the program and waits for the robot to stop. timeout_ms defaults to 2000 and is usually no more than 500 ms.

bool RLTaskAPI::PauseTask(const std::string &task_name)

Pauses only the specified task.

bool RLTaskAPI::StopRun()

Stops execution. Stopping deletes the task. Reload it before running again.

Warning: This changes the controller task state.

See also StartRun().

std::pair<std::string, int> RLTaskAPI::GetPointedLine(const std::string &task_name = "")

Returns the file and line of the program pointer. The line may be off by 1.

See also SetPointedLine(), GetExecLine().

std::pair<std::string, int> RLTaskAPI::GetExecLine(const std::string &task_name = "")

Returns the file and line of the motion pointer. The line may be off by 1.

See also SetExecLine().

int RLTaskAPI::SetPointedLine(const std::string &task_name, const std::string &file_name, int line)

Sets the program pointer. Returns 0 on success.

int RLTaskAPI::SetExecLine(const std::string &task_name, const std::string &file_name, int line)

Sets the motion pointer. Returns 0 on success.

bool RLTaskAPI::IsTaskExists(const std::string &name)

Returns whether a task named name exists.

bool RLTaskAPI::IsTaskRunning(const std::string &task_name)

bool RLTaskAPI::IsTaskRunning()

The overload with task_name checks whether that task is running. The no-argument overload checks whether any task is running.

These are overloaded functions.

---

io/analog_api.hpp

Header:	#include "io/analog_api.hpp"

Analog Class

The Analog class provides access to AI / AO / DI / DO / GI / GO and internal registers.

Header:	#include "io/analog_api.hpp"
Access:	Analog::getInstance()
Namespace:	xcore_api::io

Public Functions

[static] Analog *	getInstance()
bool	GetAIValue(const std::string &signal_name, double &value)
bool	GetAOValue(const std::string &signal_name, double &value)
bool	SetAOValue(const std::string &signal_name, const double value)
bool	GetDIValue(const std::string &signal_name, bool &value)
bool	GetDOValue(const std::string &signal_name, bool &value)
bool	SetDOValue(const std::string &signal_name, const bool value)
bool	GetGIValue(const std::string &signal_name, unsigned int &value)
bool	GetGOValue(const std::string &signal_name, unsigned int &value)
bool	SetGOValue(const std::string &signal_name, const unsigned int value)
int	WriteInt16Register(const std::string &name, const int16_t &value, int bias)
int	WriteBoolRegister(const std::string &name, const bool &value, int bias)
int	WriteFloatRegister(const std::string &name, const float &value, int bias)
int	WriteBitRegister(const std::string &name, const bool &value, int bias)
int	WriteInt32Register(const std::string &name, const int32_t &value, int bias)
int	WriteByteRegister(const std::string &name, const uint8_t &value, int bias)
int	ReadInt16Register(const std::string &name, int16_t &value, int bias)
int	ReadBoolRegister(const std::string &name, bool &value, int bias)
int	ReadFloatRegister(const std::string &name, float &value, int bias)
int	ReadBitRegister(const std::string &name, bool &value, int bias)
int	ReadInt32Register(const std::string &name, int32_t &value, int bias)
int	ReadByteRegister(const std::string &name, uint8_t &value, int bias)
bool	IsAiExist(const std::string &signal_name)
bool	IsAoExist(const std::string &signal_name)
bool	IsDiExist(const std::string &signal_name)
bool	IsDoExist(const std::string &signal_name)
bool	IsGiExist(const std::string &signal_name)
bool	IsGoExist(const std::string &signal_name)
bool	RegisterType(const std::string &register_name, std::string &type)
bool	RegisterWriteable(const std::string &register_name, bool &writeable)
bool	CheckRegisterCanUsedAsIO(const std::string &register_name, const std::string &io_type)

Detailed Description

Get the singleton with getInstance(). Signal read/write returns true on success and false if the signal does not exist. Register read/write returns 0 on success. AI / DI / GI are read-only.

Confirm that the name, address, data type, and target architecture match before reading or writing.

Warning: Writing AO / DO / GO or a register changes field signals.

See also Communication Module.

Member Function Documentation

[static] Analog *Analog::getInstance()

Returns the Analog singleton.

bool Analog::GetAIValue(const std::string &signal_name, double &value)

Reads AI. Writes value on success. Returns false if the signal does not exist.

bool Analog::GetAOValue(const std::string &signal_name, double &value)

Reads AO.

See also SetAOValue().

bool Analog::SetAOValue(const std::string &signal_name, const double value)

Writes AO.

Warning: This changes field analog output.

bool Analog::GetDIValue(const std::string &signal_name, bool &value)

Reads DI.

bool Analog::GetDOValue(const std::string &signal_name, bool &value)

Reads DO.

See also SetDOValue().

bool Analog::SetDOValue(const std::string &signal_name, const bool value)

Writes DO.

Warning: This changes field digital output.

bool Analog::GetGIValue(const std::string &signal_name, unsigned int &value)

Reads GI.

bool Analog::GetGOValue(const std::string &signal_name, unsigned int &value)

Reads GO.

See also SetGOValue().

bool Analog::SetGOValue(const std::string &signal_name, const unsigned int value)

Writes GO. Returns false if the signal does not exist or the value is out of range.

int Analog::WriteInt16Register(const std::string &name, const int16_t &value, int bias)

Writes an int16 register by name and offset. Returns 0 on success.

See also ReadInt16Register().

int Analog::WriteBoolRegister(const std::string &name, const bool &value, int bias)

Writes a bool register.

int Analog::WriteFloatRegister(const std::string &name, const float &value, int bias)

Writes a float register.

int Analog::WriteBitRegister(const std::string &name, const bool &value, int bias)

Writes a bit register.

int Analog::WriteInt32Register(const std::string &name, const int32_t &value, int bias)

Writes an int32 register.

int Analog::WriteByteRegister(const std::string &name, const uint8_t &value, int bias)

Writes a byte register.

int Analog::ReadInt16Register(const std::string &name, int16_t &value, int bias)

Reads an int16 register.

int Analog::ReadBoolRegister(const std::string &name, bool &value, int bias)

Reads a bool register.

int Analog::ReadFloatRegister(const std::string &name, float &value, int bias)

Reads a float register.

int Analog::ReadBitRegister(const std::string &name, bool &value, int bias)

Reads a bit register.

int Analog::ReadInt32Register(const std::string &name, int32_t &value, int bias)

Reads an int32 register.

int Analog::ReadByteRegister(const std::string &name, uint8_t &value, int bias)

Reads a byte register.

bool Analog::IsAiExist(const std::string &signal_name)

Returns whether the AI exists.

bool Analog::IsAoExist(const std::string &signal_name)

Returns whether the AO exists.

bool Analog::IsDiExist(const std::string &signal_name)

Returns whether the DI exists.

bool Analog::IsDoExist(const std::string &signal_name)

Returns whether the DO exists.

bool Analog::IsGiExist(const std::string &signal_name)

Returns whether the GI exists.

bool Analog::IsGoExist(const std::string &signal_name)

Returns whether the GO exists.

bool Analog::RegisterType(const std::string &register_name, std::string &type)

Looks up the register type by name and writes type (int16, bool, float, bit, int32, byte). Returns false if the register does not exist.

bool Analog::RegisterWriteable(const std::string &register_name, bool &writeable)

Queries whether the register is writable. Returns false if the register does not exist.

bool Analog::CheckRegisterCanUsedAsIO(const std::string &register_name, const std::string &io_type)

Returns whether the register can stand in for the given IO type. Returns true when it can.

---

registers/function_code_api.hpp

Header:	#include "registers/function_code_api.hpp"

A plugin can declare a function-code class, define supported register types, length, and read/write attributes, and implement the execution logic. After registration it appears in the HMI function-code list. See Communication Module.

Macros

DECLARE_FUNCTION_CODE_API(type_name)

Declares function-code class type_name, makes it inherit FuncCodeAPI, and implements Clone().

See also FUNCTION_CODE_EXECUTE_API(), RegFuncCodeAPI().

FUNCTION_CODE_EXECUTE_API(type_name)

Defines the ExecFuncCode() body of type_name.

Enum Types

enum xcore_api::registers::RegTypeAPI

This enum type describes the register data type.

Constant	Description
BIT	Bit
BOOL	Boolean
BYTE	Byte
INT16	16-bit integer
INT32	32-bit integer
FLOAT	Floating point

FuncCodeCfgAPI Class

The FuncCodeCfgAPI class describes the function-code name, supported types, length, and whether it is writable.

Header:	#include "registers/function_code_api.hpp"
Namespace:	xcore_api::registers

Public Functions

	FuncCodeCfgAPI()
virtual	~FuncCodeCfgAPI()
bool	SetName(const std::string &name)
std::string	GetName()
bool	SetSupportType(const std::vector<RegTypeAPI> &v)
std::vector<RegTypeAPI>	GetSupportType()
bool	SetLen(uint32_t len)
uint32_t	GetLen()
bool	SetWriteable(bool writeable)
bool	IsWriteable()

Member Function Documentation

bool FuncCodeCfgAPI::SetName(const std::string &name)

Sets the function-code name. Returns true on success.

std::string FuncCodeCfgAPI::GetName()

Returns the function-code name.

bool FuncCodeCfgAPI::SetSupportType(const std::vector<RegTypeAPI> &v)

Sets the set of supported register types.

std::vector<RegTypeAPI> FuncCodeCfgAPI::GetSupportType()

Returns the set of supported types.

bool FuncCodeCfgAPI::SetLen(uint32_t len)

Sets the register length.

uint32_t FuncCodeCfgAPI::GetLen()

Returns the register length.

bool FuncCodeCfgAPI::SetWriteable(bool writeable)

Sets the read/write attribute. writeable true is a write type, false is a read type.

A read-only register runs the function code when the value changes. A write-only register writes the register after the function code runs.

bool FuncCodeCfgAPI::IsWriteable()

Returns whether this is a write type.

FuncCodeAPI Class

The FuncCodeAPI class is the function-code base class. A derived class must implement ExecFuncCode() and Clone().

Header:	#include "registers/function_code_api.hpp"
Namespace:	xcore_api::registers

Public Functions

	FuncCodeAPI(const FuncCodeCfgAPI &cfg)
virtual	~FuncCodeAPI()
[pure virtual] bool	ExecFuncCode()
[pure virtual] std::shared_ptr<FuncCodeAPI>	Clone()
FuncCodeCfgAPI	GetCfg()
int	ReadIntRegValue(std::vector<int> &v)
int	ReadFloatRegValue(std::vector<float> &v)
int	WriteIntRegValue(const std::vector<int> &v)
int	WriteFloatRegValue(const std::vector<float> &v)

Detailed Description

Declare a derived class with DECLARE_FUNCTION_CODE_API(), then register it with RegFuncCodeAPI().

See also Communication Module.

Member Function Documentation

[pure virtual] bool FuncCodeAPI::ExecFuncCode()

Function-code execution logic. Returns true on success.

[pure virtual] std::shared_ptr<FuncCodeAPI> FuncCodeAPI::Clone()

Clones the current function-code instance. DECLARE_FUNCTION_CODE_API() already provides a default implementation.

FuncCodeCfgAPI FuncCodeAPI::GetCfg()

Returns the function-code configuration.

int FuncCodeAPI::ReadIntRegValue(std::vector<int> &v)

Reads the associated integer registers. Returns 0 on success.

int FuncCodeAPI::ReadFloatRegValue(std::vector<float> &v)

Reads the associated floating-point registers. Returns 0 on success.

int FuncCodeAPI::WriteIntRegValue(const std::vector<int> &v)

Writes integer registers. Returns 0 on success.

int FuncCodeAPI::WriteFloatRegValue(const std::vector<float> &v)

Writes floating-point registers. Returns 0 on success.

Related Non-Members

bool xcore_api::registers::RegFuncCodeAPI(std::shared_ptr<FuncCodeAPI> ptr)

Registers the function code with the controller. Returns true on success. Call this from Init().

See also DECLARE_FUNCTION_CODE_API().

---

ethercat/ecat_base_api.hpp

Header:	#include "ethercat/ecat_base_api.hpp"

See const_data/ecat_api.hpp for PDO / SDO data structures. See Communication Module for usage.

EcatBaseAPI Class

The EcatBaseAPI class operates PDO and SDO of a given slave. Secondary development usually inherits this class, registers objects in the derived class, then reads and writes.

Header:	#include "ethercat/ecat_base_api.hpp"
Namespace:	xcore_api::ecat

Public Functions

	EcatBaseAPI(uint16_t slave_id)
virtual	~EcatBaseAPI()
int	GetPdoValue(const PdoAPI &obj, void *value, bool bOutputData = false)
int	SetPdoValue(const PdoAPI &obj, void *value)
int	SetSdoValue(SdoAPI &sdo, void *value)
int	GetSdoValue(SdoAPI &sdo, void *value)

Protected Functions

bool	InitEcat()
int	RegisterPdo(PdoAPI &pdo, uint16_t baseIndex, uint16_t byteoffs, uint16_t byteLen)
int	RegisterSdo(SdoAPI &sdo, uint16_t index, uint16_t subIndex, uint16_t dateLen, uint16_t timeOut, const ThreadFunc &func)

Detailed Description

Pass the slave ID to the constructor. The data pointer must be large enough for the object. Unless noted otherwise, 0 means success.

Member Function Documentation

int EcatBaseAPI::GetPdoValue(const PdoAPI &obj, void *value, bool bOutputData = false)

Reads PDO. bOutputData true reads output data, false reads input data. The buffer pointed to by value must be large enough. Returns 0 on success.

See also SetPdoValue(), PdoAPI.

int EcatBaseAPI::SetPdoValue(const PdoAPI &obj, void *value)

Writes PDO. Returns 0 on success.

int EcatBaseAPI::SetSdoValue(SdoAPI &sdo, void *value)

Writes SDO. Returns 0 on success.

See also GetSdoValue(), SdoAPI.

int EcatBaseAPI::GetSdoValue(SdoAPI &sdo, void *value)

Reads SDO. Returns 0 on success.

bool EcatBaseAPI::InitEcat()

Initializes EtherCAT. Returns true on success. Call this from a derived-class initialization flow.

int EcatBaseAPI::RegisterPdo(PdoAPI &pdo, uint16_t baseIndex, uint16_t byteoffs, uint16_t byteLen)

Registers a PDO with the given base index, byte offset, and length. Returns 0 on success.

int EcatBaseAPI::RegisterSdo(SdoAPI &sdo, uint16_t index, uint16_t subIndex, uint16_t dateLen, uint16_t timeOut, const ThreadFunc &func)

Registers an SDO. The spellings dateLen and timeOut match the header. Returns 0 on success.

---

fieldbus/fieldbus_api.hpp

Header:	#include "fieldbus/fieldbus_api.hpp"

Wraps creating, configuring, opening, and closing fieldbus devices, plus register read/write and DI / DO access. See Communication Module.

Enum Types

enum xcore_api::fieldbus::DeviceTypeAPI

This enum type describes the fieldbus device type.

Constant	Description
MODBUS_TCP_MASTER	Modbus TCP master
MODBUS_TCP_SLAVER	Modbus TCP slave
MODBUS_RTU_MASTER	Modbus RTU master
MODBUS_RTU_SLAVER	Modbus RTU slave
PROFINET_SLAVER	Profinet slave
EIP_SLAVER	EtherNet/IP slave
CCLINK_IE_SLAVER	CC-Link IE slave
CCLINK_ECAT_SLAVER	CC-Link EtherCAT slave

The spelling SLAVER in the constant names matches the header.

enum xcore_api::fieldbus::EndianAPI

This enum type describes the endianness of register data.

Constant	Description
ABCD	Big endian
CDAB	Big-endian bytes, little-endian words
BADC	Little-endian bytes, big-endian words
DCBA	Little-endian bytes and words

FieldbusCfgAPI Class

The FieldbusCfgAPI class is the base configuration of a fieldbus device, including device type, name, and endianness.

Header:	#include "fieldbus/fieldbus_api.hpp"
Namespace:	xcore_api::fieldbus

Public Functions

	FieldbusCfgAPI()
	FieldbusCfgAPI(DeviceTypeAPI type)
virtual	~FieldbusCfgAPI()
void	Reset(DeviceTypeAPI type)
int	SetName(const std::string &value)
std::string	GetName()
int	SetEndian(EndianAPI endian)
EndianAPI	GetEndian()

Member Function Documentation

void FieldbusCfgAPI::Reset(DeviceTypeAPI type)

Resets the device type.

int FieldbusCfgAPI::SetName(const std::string &value)

Sets the device name. Returns 0 on success.

std::string FieldbusCfgAPI::GetName()

Returns the device name. The default is empty.

int FieldbusCfgAPI::SetEndian(EndianAPI endian)

Sets the endianness. Returns 0 on success.

EndianAPI FieldbusCfgAPI::GetEndian()

Returns the endianness.

ModbusCfgAPI Class

The ModbusCfgAPI class describes the IP, port, serial port, slave ID, and register / coil counts of Modbus TCP / RTU.

Header:	#include "fieldbus/fieldbus_api.hpp"
Inherits:	FieldbusCfgAPI

Public Functions

	ModbusCfgAPI(DeviceTypeAPI type)
void	SetIp(const std::string &value)
const std::string	GetIp() const
void	SetPort(const uint32_t &value)
const uint32_t	GetPort() const
void	SetSerialName(const std::string &value)
const std::string	GetSerialName() const
void	SetSlaverId(const uint32_t &value)
const uint32_t	GetSlaverId() const
void	SetHoldRegStartAddr(const uint32_t &value)
const uint32_t	GetHoldRegStartAddr() const
void	SetHoldRegNum(const uint32_t &value)
const uint32_t	GetHoldRegNum() const
void	SetInputRegStartAddr(const uint32_t &value)
const uint32_t	GetInputRegStartAddr() const
void	SetInputRegNum(const uint32_t &value)
const uint32_t	GetInputRegNum() const
void	SetCoilsStartAddr(const uint32_t &value)
const uint32_t	GetCoilsStartAddr() const
void	SetCoilsNum(const uint32_t &value)
const uint32_t	GetCoilsNum() const
void	SetDiscInputStartAddr(const uint32_t &value)
const uint32_t	GetDiscInputStartAddr() const
void	SetDiscInputNum(const uint32_t &value)
const uint32_t	GetDiscInputNum() const

Detailed Description

TCP types use SetIp() and SetPort(). RTU types use SetSerialName(). If a slave does not support reading coils or discrete inputs, set the corresponding count to 0. Otherwise function may be affected.

Member Function Documentation

void ModbusCfgAPI::SetIp(const std::string &value)

Sets the IP. Valid only for Modbus TCP.

const std::string ModbusCfgAPI::GetIp() const

Returns the IP.

void ModbusCfgAPI::SetPort(const uint32_t &value)

Sets the port. Valid only for Modbus TCP.

const uint32_t ModbusCfgAPI::GetPort() const

Returns the port.

void ModbusCfgAPI::SetSerialName(const std::string &value)

Sets the serial-port name. Valid only for Modbus RTU.

const std::string ModbusCfgAPI::GetSerialName() const

Returns the serial-port name.

void ModbusCfgAPI::SetSlaverId(const uint32_t &value)

Sets the slave ID. The spelling Slaver in the function name matches the header.

const uint32_t ModbusCfgAPI::GetSlaverId() const

Returns the slave ID.

void ModbusCfgAPI::SetHoldRegStartAddr(const uint32_t &value)

Sets the holding-register start address.

const uint32_t ModbusCfgAPI::GetHoldRegStartAddr() const

Returns the holding-register start address.

void ModbusCfgAPI::SetHoldRegNum(const uint32_t &value)

Sets the holding-register count.

const uint32_t ModbusCfgAPI::GetHoldRegNum() const

Returns the holding-register count.

void ModbusCfgAPI::SetInputRegStartAddr(const uint32_t &value)

Sets the input-register start address.

const uint32_t ModbusCfgAPI::GetInputRegStartAddr() const

Returns the input-register start address.

void ModbusCfgAPI::SetInputRegNum(const uint32_t &value)

Sets the input-register count.

const uint32_t ModbusCfgAPI::GetInputRegNum() const

Returns the input-register count.

void ModbusCfgAPI::SetCoilsStartAddr(const uint32_t &value)

Sets the coil start address.

const uint32_t ModbusCfgAPI::GetCoilsStartAddr() const

Returns the coil start address.

void ModbusCfgAPI::SetCoilsNum(const uint32_t &value)

Sets the coil count. Set this to 0 if the slave does not support it.

const uint32_t ModbusCfgAPI::GetCoilsNum() const

Returns the coil count.

void ModbusCfgAPI::SetDiscInputStartAddr(const uint32_t &value)

Sets the discrete-input start address.

const uint32_t ModbusCfgAPI::GetDiscInputStartAddr() const

Returns the discrete-input start address.

void ModbusCfgAPI::SetDiscInputNum(const uint32_t &value)

Sets the discrete-input count. Set this to 0 if the slave does not support it.

const uint32_t ModbusCfgAPI::GetDiscInputNum() const

Returns the discrete-input count.

ProfinetCfgAPI Class

The ProfinetCfgAPI class describes the Profinet station name, NIC, update period, and slot module IDs.

Header:	#include "fieldbus/fieldbus_api.hpp"
Inherits:	FieldbusCfgAPI

Public Functions

	ProfinetCfgAPI(DeviceTypeAPI type)
void	SetStationName(const std::string &value)
const std::string	GetStationName() const
void	SetNetcard(const std::string &value)
const std::string	GetNetcard() const
void	SetUpdateDataInternal(const uint32_t &value)
const uint32_t	GetUpdateDataInternal() const
void	SetSlot1ModuleID(const uint32_t &value)
const uint32_t	GetSlot1ModuleID() const
void	SetSlot2ModuleID(const uint32_t &value)
const uint32_t	GetSlot2ModuleID() const
void	SetSlot3MmoduleID(const uint32_t &value)
const uint32_t	GetSlot3ModuleID() const
void	SetSlot4ModuleID(const uint32_t &value)
const uint32_t	GetSlot4ModuleID() const
void	SetSlot5ModuleID(const uint32_t &value)
const uint32_t	GetSlot5ModuleID() const
void	SetSlot6ModuleID(const uint32_t &value)
const uint32_t	GetSlot6ModuleID() const

Member Function Documentation

void ProfinetCfgAPI::SetStationName(const std::string &value)

Sets the station name.

const std::string ProfinetCfgAPI::GetStationName() const

Returns the station name.

void ProfinetCfgAPI::SetNetcard(const std::string &value)

Sets the NIC. The spelling Netcard in the function name matches the header.

const std::string ProfinetCfgAPI::GetNetcard() const

Returns the NIC.

void ProfinetCfgAPI::SetUpdateDataInternal(const uint32_t &value)

Sets the update period. The spelling Internal in the function name matches the header.

const uint32_t ProfinetCfgAPI::GetUpdateDataInternal() const

Returns the update period.

void ProfinetCfgAPI::SetSlot1ModuleID(const uint32_t &value)

Sets the slot 1 module ID. The setters for slots 2, 4, 5, and 6 work the same way.

const uint32_t ProfinetCfgAPI::GetSlot1ModuleID() const

Returns the slot 1 module ID. The getters for slots 2 through 6 work the same way.

void ProfinetCfgAPI::SetSlot2ModuleID(const uint32_t &value)

Sets the slot 2 module ID.

const uint32_t ProfinetCfgAPI::GetSlot2ModuleID() const

Returns the slot 2 module ID.

void ProfinetCfgAPI::SetSlot3MmoduleID(const uint32_t &value)

Sets the slot 3 module ID. The spelling Mmodule in the function name matches the header.

const uint32_t ProfinetCfgAPI::GetSlot3ModuleID() const

Returns the slot 3 module ID.

void ProfinetCfgAPI::SetSlot4ModuleID(const uint32_t &value)

Sets the slot 4 module ID.

const uint32_t ProfinetCfgAPI::GetSlot4ModuleID() const

Returns the slot 4 module ID.

void ProfinetCfgAPI::SetSlot5ModuleID(const uint32_t &value)

Sets the slot 5 module ID.

const uint32_t ProfinetCfgAPI::GetSlot5ModuleID() const

Returns the slot 5 module ID.

void ProfinetCfgAPI::SetSlot6ModuleID(const uint32_t &value)

Sets the slot 6 module ID.

const uint32_t ProfinetCfgAPI::GetSlot6ModuleID() const

Returns the slot 6 module ID.

EipCfgAPI Class

The EipCfgAPI class describes the EtherNet/IP read/write register counts and NIC.

Header:	#include "fieldbus/fieldbus_api.hpp"
Inherits:	FieldbusCfgAPI

Public Functions

	EipCfgAPI(DeviceTypeAPI type)
void	SetReadRegNum(const uint16_t &value)
const uint16_t	GetReadRegNum() const
void	SetWriteRegNum(const uint16_t &value)
const uint16_t	GetWriteRegNum() const
void	SetNetCard(const std::string &value)
const std::string	GetNetCard() const

Member Function Documentation

void EipCfgAPI::SetReadRegNum(const uint16_t &value)

Sets the read-register count.

const uint16_t EipCfgAPI::GetReadRegNum() const

Returns the read-register count.

void EipCfgAPI::SetWriteRegNum(const uint16_t &value)

Sets the write-register count.

const uint16_t EipCfgAPI::GetWriteRegNum() const

Returns the write-register count.

void EipCfgAPI::SetNetCard(const std::string &value)

Sets the NIC.

const std::string EipCfgAPI::GetNetCard() const

Returns the NIC.

CCLinkCfgAPI Class

The CCLinkCfgAPI class describes the CC-Link protocol type, NIC, occupied station count, baud rate, and protocol version.

Header:	#include "fieldbus/fieldbus_api.hpp"
Inherits:	FieldbusCfgAPI

Public Functions

	CCLinkCfgAPI(DeviceTypeAPI type)
void	SetProtoType(const std::string &value)
const std::string	GetProtoType() const
void	SetNetCard(const std::string &value)
const std::string	GetNetCard() const
void	SetOccupiedStaNum(const uint32_t &value)
const uint32_t	GetOccupiedStationNum() const
void	SetBaudRate(const uint32_t &value)
const uint32_t	GetBaudRate() const
void	SetProtoVersion(const uint32_t &value)
const uint32_t	GetProtoVersion() const

Member Function Documentation

void CCLinkCfgAPI::SetProtoType(const std::string &value)

Sets the protocol type.

const std::string CCLinkCfgAPI::GetProtoType() const

Returns the protocol type.

void CCLinkCfgAPI::SetNetCard(const std::string &value)

Sets the NIC.

const std::string CCLinkCfgAPI::GetNetCard() const

Returns the NIC.

void CCLinkCfgAPI::SetOccupiedStaNum(const uint32_t &value)

Sets the occupied station count.

const uint32_t CCLinkCfgAPI::GetOccupiedStationNum() const

Returns the occupied station count.

void CCLinkCfgAPI::SetBaudRate(const uint32_t &value)

Sets the baud rate.

const uint32_t CCLinkCfgAPI::GetBaudRate() const

Returns the baud rate.

void CCLinkCfgAPI::SetProtoVersion(const uint32_t &value)

Sets the protocol version.

const uint32_t CCLinkCfgAPI::GetProtoVersion() const

Returns the protocol version.

FieldbusAPI Class

The FieldbusAPI class provides a unified API to open, close, read/write registers, and access DI / DO.

Header:	#include "fieldbus/fieldbus_api.hpp"
Namespace:	xcore_api::fieldbus

Public Functions

	FieldbusAPI(const FieldbusCfgAPI &cfg)
virtual	~FieldbusAPI()
int	Open()
int	Close()
int	ReadRegisters(uint32_t addr, uint16_t *dest, const uint32_t &nb = 1)
int	WriteRegisters(uint32_t addr, const uint16_t *src, const uint32_t &nb = 1)
int	GetDINum()
int	GetDONum()
int	SetDO(const uint32_t &index, const bool &value)
int	GetDI(const uint32_t &index, bool &value)

Detailed Description

Pass FieldbusCfgAPI or a derived configuration to the constructor. Unless noted otherwise, 0 means success.

See also Communication Module.

Member Function Documentation

int FieldbusAPI::Open()

Opens the fieldbus device. Returns 0 on success.

See also Close().

int FieldbusAPI::Close()

Closes the fieldbus device. Returns 0 on success.

int FieldbusAPI::ReadRegisters(uint32_t addr, uint16_t *dest, const uint32_t &nb = 1)

Reads nb registers from addr into dest. nb defaults to 1. Returns 0 on success.

See also WriteRegisters().

int FieldbusAPI::WriteRegisters(uint32_t addr, const uint16_t *src, const uint32_t &nb = 1)

Writes nb registers from src to addr. Returns 0 on success.

int FieldbusAPI::GetDINum()

Returns the DI count.

int FieldbusAPI::GetDONum()

Returns the DO count.

int FieldbusAPI::SetDO(const uint32_t &index, const bool &value)

Sets a DO by index. Returns 0 on success.

Warning: This changes field digital output.

int FieldbusAPI::GetDI(const uint32_t &index, bool &value)

Reads a DI by index. Writes value on success.

---

endtool/endtool_api.hpp

Header:	#include "endtool/endtool_api.hpp"

Used to control devices such as electric grippers through end-tool protocol passthrough. Currently it mainly wraps Modbus RTU.

ModbusRTUEndtoolAPI Class

The ModbusRTUEndtoolAPI class wraps common Modbus RTU function codes for end tools.

Header:	#include "endtool/endtool_api.hpp"
Namespace:	xcore_api::endtool

Public Functions

	ModbusRTUEndtoolAPI()
virtual	~ModbusRTUEndtoolAPI()
bool	RWData(const int &send_len, const std::vector<uint8_t> &send_data, const int &rev_len, std::vector<uint8_t> &rev_data, int &ret_status)
bool	ReadCoil_01(const int &slave_id, const uint16_t &addr, const int &len, std::vector<bool> &data, bool crc_inverse = false)
bool	ReadDiscreteInput_02(const int &slave_id, const uint16_t &addr, const int &len, std::vector<bool> &data, bool crc_inverse = false)
bool	ReadRegister_03(const int &slave_id, const uint16_t &addr, const uint16_t &len, std::vector<uint16_t> &data, bool crc_inverse = false)
bool	ReadRegister_04(const int &slave_id, const uint16_t &addr, const uint16_t &len, std::vector<uint16_t> &data, bool crc_inverse = false)
bool	WriteCoil_05(const int &slave_id, const uint16_t &addr, const int &len, std::vector<bool> &data, bool crc_inverse = false)
bool	WriteRegister_06(const int &slave_id, const uint16_t &addr, const uint16_t &len, const std::vector<uint16_t> &data, bool crc_inverse = false)
bool	WriteCoil_0F(const int &slave_id, const uint16_t &addr, const int &len, std::vector<bool> &data, bool crc_inverse = false)
bool	WriteRegister_10(const int &slave_id, const uint16_t &addr, const uint16_t &len, const std::vector<uint16_t> &data, bool crc_inverse = false)

Detailed Description

Use this to wrap private protocols of end tools such as grippers, tool changers, and sensors. crc_inverse controls whether CRC is inverted. Returns true on success.

Member Function Documentation

bool ModbusRTUEndtoolAPI::RWData(const int &send_len, const std::vector<uint8_t> &send_data, const int &rev_len, std::vector<uint8_t> &rev_data, int &ret_status)

Sends and receives raw data directly. ret_status is the return status.

bool ModbusRTUEndtoolAPI::ReadCoil_01(const int &slave_id, const uint16_t &addr, const int &len, std::vector<bool> &data, bool crc_inverse = false)

Reads coils. Function code 01.

bool ModbusRTUEndtoolAPI::ReadDiscreteInput_02(const int &slave_id, const uint16_t &addr, const int &len, std::vector<bool> &data, bool crc_inverse = false)

Reads discrete inputs. Function code 02.

bool ModbusRTUEndtoolAPI::ReadRegister_03(const int &slave_id, const uint16_t &addr, const uint16_t &len, std::vector<uint16_t> &data, bool crc_inverse = false)

Reads holding registers. Function code 03.

bool ModbusRTUEndtoolAPI::ReadRegister_04(const int &slave_id, const uint16_t &addr, const uint16_t &len, std::vector<uint16_t> &data, bool crc_inverse = false)

Reads input registers. Function code 04.

bool ModbusRTUEndtoolAPI::WriteCoil_05(const int &slave_id, const uint16_t &addr, const int &len, std::vector<bool> &data, bool crc_inverse = false)

Writes a single coil. Function code 05.

bool ModbusRTUEndtoolAPI::WriteRegister_06(const int &slave_id, const uint16_t &addr, const uint16_t &len, const std::vector<uint16_t> &data, bool crc_inverse = false)

Writes a single register. Function code 06.

bool ModbusRTUEndtoolAPI::WriteCoil_0F(const int &slave_id, const uint16_t &addr, const int &len, std::vector<bool> &data, bool crc_inverse = false)

Writes multiple coils. Function code 15.

bool ModbusRTUEndtoolAPI::WriteRegister_10(const int &slave_id, const uint16_t &addr, const uint16_t &len, const std::vector<uint16_t> &data, bool crc_inverse = false)

Writes multiple registers. Function code 16.

---

service/service_api.hpp

Header:	#include "service/service_api.hpp"

Registers a custom JSON protocol in a controller plugin. After the client sends a request with plugin_name and key, the controller calls the registered callback and returns the JSON it produces. See Client Interaction.

Related Non-Members

int xcore_api::service::RegServiceAPI(const std::string &plugin_name, const std::string &key, const std::function &func)

Registers one service protocol. plugin_name is the plugin name, key is the protocol key, and func receives the request JSON and returns the response JSON. Returns 0 on success.

Register this in Start(). Use it to read state, send configuration, or implement lightweight inter-plugin communication with JSON.

See also Client Interaction.

---

log/log_api.hpp

Header:	#include "log/log_api.hpp"

Initializes a plugin-specific log and provides log macros prefixed with the plugin name. See log Library Usage.

Macros

Macro	Level
LOG_DEBUG / LOG_INFO / LOG_WARNING / LOG_ERROR / LOG_FATAL	Debug / Info / Warning / Error / Fatal

Macro Notes

The usage is similar to stream output:

LOG_INFO << "hello world";

Notes

Use the customized macros in this header. Without them, logs are written together with the controller logs. Total log storage must not exceed 1 GB.

See also InitLogAPI(), log Library Usage.

Related Non-Members

int xcore_api::log::InitLogAPI(const std::string &dir, size_t max_size, size_t max_nubmer)

Initializes plugin logs. dir is the storage directory relative to the plugin data directory. max_size is the per-file size limit in MB. max_nubmer is the file count; the parameter spelling matches the header. Returns 0 on success.

Call this from Init().

The header also declares xcore_api::log::PLUGIN, whose value is the return of GetPluginNameAPI(), for the log-level prefix.

---

user_log/user_log_api.hpp

Header:	#include "user_log/user_log_api.hpp"

Registers and reports multilingual user logs and runtime logs with the controller. Load the configuration in Init() and register log codes in Start(). See User Log Reporting.

Related Non-Members

int xcore_api::user_log::ConfigReportLogAPI(const Json::Value &val)

Configures multilingual logs for this plugin. Must be called from Init(). Returns 0 on success.

See also ConfigEnglishReportLogAPI(), RegisterReportLogAPI().

int xcore_api::user_log::ConfigEnglishReportLogAPI(const Json::Value &val)

Configures the English fallback logs. Must be called from Init(). Returns 0 on success.

int xcore_api::user_log::RegisterReportLogAPI()

Registers the configured log codes with the controller so they take effect. Must be called from Start(). Returns 0 on success.

void xcore_api::user_log::ReportUserLogAPI(int log_no, const std::string &detail = "", const std::string &context = "")

Reports a multilingual user log. log_no is the log number, detail is the detailed-reason key, and context replaces $arg in the text.

void xcore_api::user_log::ReportRunLogAPI(int log_no, const std::string &arg = "", const std::string &detail = "")

Reports a user runtime log. log_no is the RunLog number. arg replaces $arg in content. detail is shown on the client detail page.

---

const_data/pose_api.hpp

Header:	#include "const_data/pose_api.hpp"

Defines common motion data structures for controller plugins, using SI units: meters, radians, and kilograms. These types support operator<< and can be written to logs directly.

PositionAPI Struct

The PositionAPI struct describes a position in meters.

Member	Type	Description
x / y / z	double	Coordinates in meters

QuaternionAPI Struct

The QuaternionAPI struct describes an orientation quaternion. The default is (1, 0, 0, 0).

Member	Type	Description
q1 / q2 / q3 / q4	double	Quaternion components

ConfDataAPI Struct

The ConfDataAPI struct describes the robot configuration used to choose a solution to the target.

Member	Type	Description
cfx / cf1–cf7	int	Configuration components

PoseAPI Struct

The PoseAPI struct describes a pose / coordinate frame.

Member	Type	Description
p	PositionAPI	Position
q	QuaternionAPI	Orientation

Supports right-multiply operator* and Inverse().

PoseAPI PoseAPI::Inverse() const

Returns the inverse of this frame.

PointAPI Struct

The PointAPI struct describes a point. It can be a Cartesian point or a joint point.

Member	Type	Description
pose	PoseAPI	Cartesian pose
joint	std::vector<double>	Joint angles in radians
is_joint	bool	Whether this is a joint point
extjoint	std::vector<double>	External axes in radians
is_ext_rad	bool	Header comment says “external axes are degrees”; default false
arm_angle	double	Arm angle of a 7-axis robot
confdata	ConfDataAPI	Configuration

ZoneAPI Struct

The ZoneAPI struct describes a zone.

Member	Type	Description
distance	double	Distance in meters
percent	double	Percent

SpeedAPI Struct

The SpeedAPI struct describes speed.

Member	Type	Description
tcpvel	double	TCP linear speed in m/s
orivel	double	Orientation speed in rad/s
psivel	double	7-axis arm angular speed
percent	double	Joint-speed percent
forced	bool	true ignores the speed slider

LoadAPI Struct

The LoadAPI struct describes a load.

Member	Type	Description
mass	double	Mass in kilograms
cog	PoseAPI	Center of gravity
ix / iy / iz	double	Moments of inertia

TriggerAPI Struct

The TriggerAPI struct describes a path trigger.

Member	Type	Description
type	TriggerType	DISTANCE or TIME
reference_is_from_start	bool	Whether the reference is from the start
value_from_reference	double	Value from the reference, in meters or seconds
trigger_callback	std::function<void()>	Trigger callback

See also MotionCmdArgsAPI::SetTriggers().

ToolAPI Struct

The ToolAPI struct describes the tool frame and tool load.

Member	Type	Description
rob_hold	bool	true is a handheld tool, false is an external tool
tool_frame	PoseAPI	Tool frame
tool_load	LoadAPI	Tool load

WobjAPI Struct

The WobjAPI struct describes the work-object frame, user frame, and work-object load.

Member	Type	Description
rob_hold	bool	true is a handheld work object, false is an external work object
wobj_frame	PoseAPI	Work-object frame relative to the user frame
wobj_load	LoadAPI	Work-object load
user_frame	PoseAPI	User frame
uf_prog	bool	Whether the user frame moves
uf_mec	std::string	Related mechanical unit
uf_id	int	User-frame ID
mech_unit	void *	Mechanical-unit data

---

const_data/ecat_api.hpp

Header:	#include "const_data/ecat_api.hpp"

Defines EtherCAT PDO / SDO data structures for ethercat.

Types

using xcore_api::const_data::ecat::ThreadFunc = std::function

SDO callback type.

PdoAPI Struct

The PdoAPI struct describes a PDO.

Member	Type	Description
baseIndex	uint16_t	Data index
byteOffs	uint16_t	Byte offset
byteSize	uint16_t	Data size
name	std::string	PDO name

See also RegisterPdo(), GetPdoValue().

SdoAPI Struct

The SdoAPI struct describes an SDO. The default timeout is 4000.

Member	Type	Description
index	uint16_t	Index
subIndex	uint8_t	Sub-index
dateLen	uint32_t	Data length. The member spelling matches the header
timeOut	uint32_t	Timeout
flags	uint32_t	Flags
m_msg_callback	ThreadFunc	Callback

See also RegisterSdo(), GetSdoValue().

---

utils/filesystem_api.hpp

Header:	#include "utils/filesystem_api.hpp"

See json Library Usage for JSON usage examples.

Related Non-Members

bool xcore_api::utils::WriteBinaryToFileAPI(const std::string &filename, const std::string &content)

Writes binary content to filename. Returns true on success.

See also ReadBinaryFromFileAPI().

bool xcore_api::utils::ReadBinaryFromFileAPI(const std::string &filename, std::string &content)

Reads binary content from filename into content. Returns true on success.

bool xcore_api::utils::LoadFromFileAPI(Json::Value &root, const std::string &file_name)

Parses JSON from a file into root. Returns true on success.

See also LoadFromStringAPI(), SaveToFileAPI().

bool xcore_api::utils::LoadFromStringAPI(Json::Value &root, const std::string &json_str)

Parses JSON from a string into root. Returns true on success.

bool xcore_api::utils::SaveToFileAPI(const Json::Value &root, const std::string &file_name)

Writes JSON to a file. Returns true on success.

std::string xcore_api::utils::SaveToStringAPI(const Json::Value &root)

Serializes JSON to a string.

std::string xcore_api::utils::SaveToStringInLineAPI(const Json::Value &root)

Serializes JSON to a string as one line.

void xcore_api::utils::CreateEmptyJsonFileAPI(const std::string &file_name)

Creates an empty JSON file.

bool xcore_api::utils::IsJsonFileAPI(const std::string &file_name)

Returns whether file_name is a JSON file.

std::string xcore_api::utils::GetPluginNameAPI()

Returns the current plugin name.

---

utils/thread_pool_api.hpp

Header:	#include "utils/thread_pool_api.hpp"

Do not block for a long time in a synchronous Hook, custom-command executor, or motion callback. Use this API for long-running work.

Related Non-Members

std::future<void> xcore_api::utils::RunInThreadPoolAPI(const std::function<void()> &func)

Runs a function with no return value in the thread pool.

See also RunInThreadPoolIntAPI().

std::future<int> xcore_api::utils::RunInThreadPoolIntAPI(const std::function<int()> &func)

Runs a function that returns int in the thread pool. Get the result with future.get().

---

utils/singleton_api.hpp

Header:	#include "utils/singleton_api.hpp"

Macros

DECLARE_SINGLETON(type)

Declares a singleton friend inside the class so SingletonBaseAPI can construct type.

See also SINGLETON_INSTANCE().

SINGLETON_INSTANCE(type)

Returns the singleton pointer of type, equivalent to type::GetInstancePtr().

INIT_SINGLETON(type)

Initializes the singleton. Internally this is SINGLETON_INSTANCE().

SingletonBaseAPI Class

The SingletonBaseAPI class is the singleton base-class template.

Header:	#include "utils/singleton_api.hpp"
Namespace:	xcore_api::utils

Public Functions

	SingletonBaseAPI(const SingletonBaseAPI &) = delete
SingletonBaseAPI &	operator=(const SingletonBaseAPI &) = delete
[static] T &	GetInstance()
[static] T *	GetInstancePtr()

Detailed Description

A derived class must inherit SingletonBaseAPI<T>, use DECLARE_SINGLETON() inside the class, and make the constructor and destructor private.

class object : public xcore_api::utils::SingletonBaseAPI<object> {
    DECLARE_SINGLETON(object);
private:
    object() {}
    ~object() {}
};

Member Function Documentation

[static] T &SingletonBaseAPI::GetInstance()

Returns a reference to the singleton.

[static] T *SingletonBaseAPI::GetInstancePtr()

Returns a pointer to the singleton.

See also SINGLETON_INSTANCE().