This blog is Part 4 of a multi-part series. Make sure to check out the other blogs on this topic:

1. Epson Robots Getting Started: Create a New Project in Epson RC+
2. Epson RC+ Project Structure Explained: Files, Folders, and Flow
3. Epson Robots Commissioning Tools and Workflows in RC+
4. Epson RC+ 7.0 Robot Simulator: Setup, Testing, and Debugging

Summary

This article is the fourth in a series to explain the basics of creating a base project using Epson RC+, Epson’s software for developing and simulating an industrial robotic application. Epson offers a wide range of industrial robots for a variety of applications. Programming and configuring are done through their easy-to-use configuration software, Epson RC+, which offers many time-saving features and various add-on packages depending on the complexity of each application. In this article, we will cover the configuration of the Robot Simulator and demonstrate some useful features for simulating and testing the robot program prior to deployment in the field.

Set up Virtual Controller

The first step to simulate the robot is to configure a virtual controller. This is done through the Setup > PC to Controller Communications menu. Here, you can add a new Controller as a virtual controller. Once added, the controller can be given a different name, and then click ‘Apply’.

For this demo, we utilized the Robot model LS6-B502S. Also, important for this demo are the points used in the program logic shown below.

Using the Connection dropdown, select the new virtual controller that was created. This will start up the virtual controller and allow us to control the robot in the simulator. Open the Robot Simulator by using the toolbar icon.

Robot Simulator Environment

The Robot simulator environment has several different features and functions to test parts of the robot application. The most basic use case is to import CAD shapes or models to create a simulated environment for the application. The first 4 icons in the Robot Simulator allow the user to add 2D and 3D objects to the workspace. By default, a 2D plane is generated, with the robot placed at the world origin. Often, a robot is mounted on a pedestal that requires the user to move it with some offset relative to the origin; however, we will keep the robot at the origin for simplicity in this example.

The first objects we will add to the simulation will be two rectangles to emulate stations within the machine. Click on the SPlane_1 object, then click on the layout box (purple cube) icon at the top. The size, position, and colors were modified as shown.

Devices mounted to the robot arm, such as a camera, are configured as mounted devices. This means the device will move with the robot rather than remain in a fixed position. To attach a device to the robot, right-click on the device in the layout tree and select Part/Mounted Device Settings. Two cylinders were added to the layout to emulate a camera mounted to the end of the second robot arm. The smaller red cylinder is just added as a reference to show where the center of the camera’s field of view is located. For this cylinder, we have disabled the Collision check option, since it will not be physically present in the actual application.

CAD models can also be imported to the simulation environment using the CAD icon in the toolbar rather than relying solely on basic shapes. Supported file types include XV3, VRML, STEP, IGES, and DXF. The dialog offers options for Scale Units, rendering quality, and CAD-to-Point functionality. If CAD-to-Point is enabled, the user can generate robot points directly from the CAD model for use in the robot program. The CAD to Point function is in the toolbar at the top. Once selected, you can click on an edge, and the simulator will automatically generate points for the number of vertices found on the CAD model.

This example shows how the CAD model provides robot points for the two corners of the part tray by simply selecting the right edge of the tray’s cavity. The selected edge endpoints are shown as the yellow spheres in the screenshot below. We have exported these two points into the points file at indices 5 and 6.

The simulator can also import CAD models as ‘Hands’, which are the same as the robot’s end-of-arm tooling. The hands are treated as an extension of the robot, so they will move and rotate with the robot. When importing hands, you can adjust the mounting position and orientation to emulate the tooling assembly on the robot. Below is a CAD model imported that has different-style grippers on either end.

Testing Your Epson Robot

Now that the 3D environment is set up, you can move the robot around using the robot manager, running a program function in the ‘Run’ window, or using the Robot Operation Panel in the Simulator environment. We put together a short demo program to move the robot between a couple of positions while enabling a trace of the Tool Center Point (TCP) with a green line.

The Robot simulator also has several other useful features, such as surveillance planes and areas, recording and playback options, rendering point locations in 3D space, and much more. For more assistance with Epson Robot programming and integration, please reach out to DMC’s Industrial Automation team!

The post Epson RC+ 7.0 Robot Simulator: Setup, Testing, and Debugging appeared first on DMC, Inc..

This blog is Part 3 of a multi-part series. Make sure to check out the other blogs on this topic:

1. Epson Robots Getting Started: Create a New Project in Epson RC+
2. Epson RC+ Project Structure Explained: Files, Folders, and Flow
3. Epson Robots Commissioning Tools and Workflows in RC+
4. Epson RC+ 7.0 Robot Simulator: Setup, Testing, and Debugging

Summary

In the third entry in this series, we will be going over some useful tools for commissioning a new Epson robot and troubleshooting programs. We will discuss how to configure the robot controller, operate the robot manually, teach and configure the points and coordinates required for the application, and highlight useful tools for troubleshooting and testing the robot program.

System Configuration: Defining Controller Behavior

The first step in commissioning an Epson robot is to configure the controller through the System Configuration menu. You can access this window by navigating to the toolbar and selecting Setup, then System Configuration. This area defines how the controller behaves at startup and establishes several foundational settings that impact safety, operability, and overall workflow during commissioning and production.

When the System Configuration window opens, it defaults to the Startup tab. While this tab may seem simple, the selections you make here play a critical role in how the robot transitions from power-on to operation and how engineers interact with the system during early testing.

Startup

In the Startup tab, there are two primary setup modes, ‘Auto’ and ‘Program’, as well as an option to require a password on startup.

Selecting ‘Auto’ means that when the robot is powered on, it will enter Auto mode and begin running its programs automatically. If you select ‘Program’, the robot will be stopped upon startup and wait for commands from the Epson RC+ 7.0 software. This setting is typically used in fully commissioned calls where the robot is integrated with external equipment like a PLC, safety system, or HMI.

Select ‘Program’ mode for initial commissioning. Only set the robot to ‘Auto’ mode after teaching positions and thoroughly testing programs to avoid collisions or unexpected behavior.

Controller

After confirming your startup behavior in System Configuration, the next step is to focus on the Controller section of the project tree. This area is essentially the ‘hub’ for how the controller communicates with the outside world and interprets commands. During commissioning, many issues that appear to stem from the program (robot won’t start, IO won’t respond, remote start won’t work) trace back to controller settings.

To access these settings, expand the Controller drop-down by clicking the ‘+’ immediately to the left of Controller. This opens a set of tabs that let you define network parameters, configure device control, set up multi-robot configurations, and map fieldbus bits used for remote program selection.

Spending a few moments reviewing these sections can help ensure your controller aligns with your cell architecture before you start troubleshooting motion, IO, or PLC handshakes.

Here is a quick summary of the important sections under Controller.

• Configuration Tab: This is where you will set the IP Address and Gateway. You can also select a control device from ‘Remote IO’ or ‘PC’. Selecting ‘Remote IO’ tells the robot to listen to the remote I/O, and selecting PC tells the robot to listen to commands from the Epson RC+ 7.0 software on the connected computer.
• Robots Tab: In this tab, you can add or remove robots when you have multiple robots tied to a single controller. Press the ‘Add’ button on the right, and the following window will appear, where you can add the details of your robot.
• Inputs/Outputs Tab: This tab lets you set the byte sizes of your inputs and outputs. For your Fieldbus I/O, depending on how you are communicating with your robot, you will need to configure the byte size here.
• Remote Control Tab: Map your program control to bits in the fieldbus space using the ‘Remote Control Tab’. There are separate tabs for inputs and outputs.

Robot Manager: Controlling Power & Movement

The robot manager is the primary interface for manually interacting with the robot from your PC. In the pop-up dialog, there are several tabs where you can control the robot’s power, move the robot, teach positions and coordinate systems, configure tools, set motion limits, and more. To access the robot manager, you need to first connect the robot to the internet. Then, click the robot arm icon in the toolbar to launch the window. From there, there are a number of features that allow you to manually control your robot’s motion.

Control Panel Tab

This is the primary screen of the Robot Manager. Here you can view the status of the controller’s power and safety signals, turn the motors on or off, select your power mode, and clear any errors. In addition, you can free any axis if you want to be able to move it by hand. For 6-axis applications, you can control whether certain joints are locked or unlocked.

The top row shows the selected robot, the local coordinate system, the tool number, and the external center point (ECP). When teaching points, be sure the correct values are selected, as the taught positions depend on them.

Jog & Teach Tab

To manually move the robot and teach positions, navigate the Jog & Teach tab. This feature is frequently used during commissioning and point setup, as it allows you to view the robot’s current position, control its motion, and save taught points.

On the right side of the window, you can see the robot’s current position and arm orientation, along with controls for jog-distance and speed. Position data can be displayed using different coordinates, including World, Joint, or Pulse. World coordinates are the standard Cartesian values; Joint is the angle of each axis in the robot; and Pulse is the encoder reading.

On the left side, you can jog the robot using the arrow buttons. The Mode dropdown lets you choose whether to jog along a linear path or control individual axes. To teach a point, first jog the robot to the desired location, then select the appropriate point file and name, and press ‘Teach’ to save the position.

To navigate to a previously taught position, select the Execute Motion tab.

Available motion command options will vary based on the robot model you are using, but ’Go’ and ‘Move’ are the most basic. The ‘Go’ command will move your robot from its current position to the selected destination using a joint move, meaning that any combination of 1-6 robot joints could move at the same time. This type of movement will mostly be non-linear. The ‘Move’ command will move your robot linearly from its current position to the selected destination.

After selecting the desired command and destination, press ‘Execute’ to start the motion. While the robot is moving, a pop-up window will appear, showing which point it is moving to and providing a stop button that lets you halt its motion immediately if needed.

Points Tab

The Points tab displays all point files and taught positions stored on the robot. This view allows you to review, edit, and manage the positional data used by motion commands throughout the program. Each point includes X, Y, and Z values in millimeters and U, V, and W values in degrees.

From this tab, you can manually adjust point values and save changes directly to the controller. Because points are referenced symbolically in the program, any updates made here automatically apply wherever the point is used, simplifying updates during commissioning and long-term maintenance.

Locals Tab

A local coordinate system is a coordinate frame that is rotated relative to the robot’s default world coordinate system. Defining local coordinates can be useful when a robot repeatedly interacts with a specific area of a cell—especially if motion does not align cleanly with the world axes. It can also greatly simplify programming by allowing moves to be defined relative to a task rather than the global frame.

To define local coordinate systems, navigate to the Locals tab. There is a Local Wizard that walks you through the process of defining a new local based on taught points. If you already know the desired origin and orientation, you can manually enter it into the table. Press ‘Apply’ after using the wizard or manually adding values to save your changes to the robot.

Tools Tab

The Tools tab is very similar to the Locals tab. Here you can define coordinate systems for your end effector. A tool wizard can walk you through setting up a tool coordinate system, or you can manually enter a coordinate system in the table. Tools are useful when used with a device at the end of the robot that is not centered on the robot arm. When commanded to move to a position with a different tool selected, the robot will move so that the tool’s center is in the correct position, rather than the robot arm.

XYZ Limits Tab

In the XYZ Limits tab, you can set limits for the X, Y, and Z axes within which your robot is allowed to move. You will need to set this up when commissioning a robot for the first time. The ‘Read’ button at the bottom of the pop-up dialog will capture the current position of the selected axis limit.

You can free all joints on your robot and move it by hand to the maximum and minimum positions to record these points. This can help quickly define the space your robot is allowed to move in. Alternatively, you can manually enter or modify any of the values.

Range Tab

The next tab we will look at is the Range tab. Here you can define the limits for the encoder pulses for each joint. Similarly to the XYZ Limits tab, you can read the current robot’s position as the maximums or minimums for any joint. Joint limits differ from XYZ limits in that they monitor each robot axis rather than the tooling position.

Home Config Tab

The last tab we will go over is Home Config. In this tab, you can set the home encoder positions for each of your joints. To set your desired joint home position in the left column Home Position, you can read the current position of a joint or manually enter its encoder value. In the right column under Home Order, you can send which order you would like each of the joints to home in. Leaving them all set to ‘Step 1’ means they will all return home simultaneously.

To test the home function, navigate to the Control Panel tab and click ‘Home’.

Testing & Troubleshooting Tools

Once the robot is configured and programs are written, effective testing and troubleshooting become critical to a successful commissioning process. Epson RC+ provides several built-in tools that allow you to test logic, monitor execution, and diagnose issues without repeatedly running the full application.

Command Window

The next feature we’ll review is the Command Window. To access the program’s editable command window, select the white icon with a carrot or greater than sign (>) in the main toolbar.

The program’s Command Window will open, allowing you to execute any SPEL+ commands for testing. For example, if you wrote a custom function called ‘Motion’, you could execute that function by typing in ‘Call Motion()’ and pressing enter. For more information on SPEL+ commands, you can reference the help document found by accessing Help > Manuals > SPEL+ Language Reference.

Run Window

The Run Window includes controls for running programs in the current project and can be accessed by clicking the grey-and-white square icon in the main toolbar. During commissioning, this tool gives engineers direct visibility into robot execution, allowing them to run programs, observe behavior in real time, and make targeted adjustments without leaving RC+. Built-in status feedback helps quickly identify pauses or faults, streamlining troubleshooting and reducing time to production.

The image shows what the run window looks like when it is opened. The white area will display all outputs from your programs and any errors that occurred. You can run specific functions by selecting the function drop-down and the desired function. This is a great tool for testing smaller portions of your program, allowing you to debug your robot without running the entire program.

If you have ‘Remote IO’ selected as the control device in your controller configuration under system configuration, the ‘Enable Remote I/O’ button will then wait for the program start command from the fieldbus input. If ‘Remote IO’ is not selected as the control device, the button will say ‘Start’, which immediately executes the selected function.

I/O Monitor

The I/O Monitor provides real‑time visibility into all configured controller inputs and outputs, along with their current states. This tool is especially useful during commissioning and debugging, as it allows you to quickly verify whether signals are being received and set as expected. The I/O Monitor’s interface opens when you click the icon of circles arranged in a square.

From the I/O Monitor, you can confirm that the fieldbus and local I/O are mapped correctly and that inputs change state when external devices, such as sensors or PLCs, are actuated. This helps isolate whether an issue is related to wiring, I/O configuration, or program logic.

Assigned I/O and their symbolic names can be viewed and managed in the I/O Label Editor, ensuring the values displayed in the monitor align with the labels used in your program. Using the I/O Monitor alongside the Run Window makes it easier to validate handshakes, troubleshoot start conditions, and confirm outputs are being driven correctly during program execution.

Task Manager

To access the Task Manager, click the icon with three documents layered over one another. After starting your robot, Task Manager is a useful place to keep track of which tasks are currently running, paused, or aborted. If a task is paused or waiting, it will show you which line it is waiting on.

After starting your robot, the Task Manager is a useful place to keep track of which tasks are currently running, paused, or aborted. If a task is paused or waiting, it will show you which line it is waiting on.

Display Variables

While running your robot program, it is useful to monitor the current value of any variables you may have defined in your programs. This is especially important during commissioning, when you are verifying logic, tuning motion, and validating system behavior against real hardware. Monitoring variable values lets you confirm that inputs, calculations, and state changes occur as expected, making it easier to identify and correct issues early.

You can do this in the Display Variables window. To access it, click ‘Run’ in the main toolbar and select ‘Display Variables’ from the drop-down. Here you can see your ‘Global’, ‘Preserved’, ‘Module’, and ‘Local’ variables, their data types, and current values.

System History

One last useful tool for testing and troubleshooting is the System History window. This is a log of errors or events that have occurred on the robot controller and can be useful for troubleshooting the robot if it stops mid-run, especially if you are at a stage in your project where you are not always connected to the robot controller using RC+. To access this window, select ‘View’ from the toolbar and click ‘System History’.

Conclusion

All these tools can be used with the virtual controller, and I would suggest testing them in the simulated environment first. This allows you to familiarize yourself with the configuration changes, which robot is used, how to perform manual moves and operations, set up the various configurations through the robot manager, and ultimately test the robot program you have developed. Using these tools with the simulated controller will also help with the first-time commissioning of the actual robotic application.

The post Epson Robots Commissioning Tools and Workflows in RC+ appeared first on DMC, Inc..

This article is the second in a series that explains the basics of creating a base project using Epson RC+, Epson’s software for developing and simulating an industrial robotic application. Epson offers a wide range of industrial robots for a variety of applications.

The programming and configuration of the robots are done through the easy-to-use configuration software, Epson RC+, which offers many time-saving features and various add-on packages depending on the complexity of each application. We will cover the overall project structure, types of files, and how they all work together in the application.

Program Files

This will contain all the logic for the robot application. You can define functions to call from within the robot program or leverage an external trigger, such as a PLC. When developing the robot application, you must have a function called “Main”. If this function is not defined, the compiler will throw an error. The main function is called when none of the 6 program bits are set. See the table below for the main functions that can be selected from the remote inputs.

The entire robot program can be written in a single program file or across many.  For organizational purposes, we generally like to separate functions into multiple programs for easier navigation, and based on which program tasks are executed. 

Include Files

Include files are generally used to define constants that can be used across the user program. To create an include file, right-click on “Include Files” in the project tree and select “New”. Fill out the dialog window as follows. We have added two constants for max parts and max speed, which can now be used in the robot program.

By putting all the constants into a single include file, we can use a single line at the top of the program file to give the functions access to use these constants. In the screenshot below, the first line contains an ‘include’ statement that references the constants file we just created. This allows the main function to use the defined constant values instead of hard-coded numbers.

Point Files

Point files are table-style views of all defined points for use in the robot program. The points can be manually adjusted from the programming environment, taught using robot manager, and assigned calculated values during program execution. Each point file contains points numbered from 0 to 999, and there can be multiple point files per robot. There can even be multiple robots per controller, depending on the application requirements.

In this example, we have simply added the two points ‘ptStart’ and ‘ptEnd’. The point files contain data for the most complicated examples, but depending on the application, some are not used. This example uses a SCARA robot, which only uses the X/Y/Z/U positions, since it is a 4-axis robot. Also included in this view is the Local coordinate system used and which Hand (Righty/Lefty) configuration the robot is in for that point.

In the program, the points can be used symbolically as shown below. The Go instruction is a move command for the robot, and the operator can simply use the point label defined in the Points file to access the robot’s positional data.

IO Labels

IO labels are used to assign symbolic names to integer values that represent input and output memory locations. These are useful when performing Input and Output mapping in the user program, rather than leveraging the hardcoded bit/byte/word values in the IO space. Below, we define 2 input bits and 2 output bits to simulate reading and writing to digital IO. The standard I/O is used for local IO on the robot, such as devices on the end-of-arm tooling.

To use these labels in the program, the user must use the proper input and output functions. Below is an example of using the Sw() function to read the status of the input bits and the On/Off functions to assign the output bit value. Notice how the IO Labels are used with these functions to make the logic more readable.

User Errors

User errors define an error space for the user to create custom error messages. The error codes reserved for this are from 8000 to 8999. When using these error messages, we can communicate the issue to an operator via the message field. This message will appear in the Status window when an error occurs in the program logic. This error code can also be used to communicate with the PLC controlling it, enabling easier diagnostics when the robot is not performing properly. A good example of this is communicating issues with tooling actuation controlled locally by the robot controller, even though the robot is part of a larger automation cell.

This example below shows the Error function used with the ‘ToolingError’ User Error we just created. When the Function fcVacuum_ON is called from elsewhere in the user program, it turns on the vacuum gripper’s output and waits for 2 seconds for the vacuum switch input to turn on. The TW value will be true if the 2-second timeout is reached, which is why the Error is thrown within the if statement in this example.

Tasks

Tasks are useful for executing the program on different threads within the robot controller’s CPU.  This allows the robot controller to process different pieces of logic simultaneously. The most useful example of this is having logic that performs Input and Output mapping in a separate task from the logic that controls the robot motion or tooling actuation. It is often desired to keep the functions used to read and write to IO running all the time, but to have the motion commands and functional logic in a task that can be paused or aborted during an Emergency Stop.

The example below shows how to start the IO monitoring function and motion logic in separate tasks. To start a new task, the ‘xqt’ instruction is used with the function that starts in the new task, and the task behavior when a Pause or Emergency Stop is issued. The IO function is set up to continuously run on Emergency Stop, where the motion logic function is set to Normal, which will respond normally to a Pause or Emergency Stop command.

Conclusion

Now you have a basic understanding of how to organize an Epson RC+ project, and you have all the tools needed to get started creating your own application. The most important starting point is to create a ‘Main’ function in a program file and define a few robot points to use in the program. Then I would suggest adding constants with include files and user errors for better troubleshooting. Finally, you could start adding different task executions for different functions. Understanding how all these components interact is vital to developing higher-quality robot programs.

The post Epson RC+ Project Structure Explained: Files, Folders, and Flow appeared first on DMC, Inc..

Here are my top five tools and suggestions to get you started with HandlingPRO: 

• Joint Jog Tool
• Fine Joint Position Control
• Change Views
• Move to Toolbar
• Fanuc Tutorials

Joint Jog Tool

This tool gives you handles that you can use to move the robot joints, but more importantly, it shows the limits of the robotic arm movements. Sometimes, it’s difficult to understand which joint is at its maximum and is causing you to reach a position limit.    

To enable this tool, navigate to Robot > Show Joint Jog Tool.   

Fine Joint Position Control

Moving the robot arm around with the joint jog tool is great for getting a broad understanding of the robot movement. If you want to dial in the movements to the millimeter, you should use the teach pendant.    

To do so you should click the position button on the bottom right half of the screen.  

Next, enable the teach pendant by clicking the ON/OFF switch on the left so that it's in the ON position.  

Note: The teach pendant-enabled switch will turn off when testing your programs and inhibits many of the editing tools, make sure that this is ON whenever developing on the teach pendant.   

Now that the teach pendant is on, you can either jog the robot with reference to the tool tip in the XYZ plane (or XYZ angles) using the blue button on the right of the teach pendant, or you can press the REPRE button on the bottom right to switch to the second mode (Joint Position Control). In this mode, you can jog each one of the individual joints by, again, using the blue buttons on the right of the teach pendant.  

Change Views

You can change your rotational axis by left-clicking anything in the window and can even select different surfaces of an object. Right-click to then rotate around that.  

Move to Toolbar

With this toolbar, you get access to a bunch of helpful tools such as move to surface or move to points that you have set up in your program.  

To enable the move to toolbar, click this button:   

Fanuc Tutorials

Lastly, Fanuc includes some helpful eLearn Training through tutorials. Some of these are built into the Help documentation and you can find them under the help tab.   

Learn more about DMC’s Robotic Integration and Automation and contact us today to get started on your next project.  

The post Top Five Fanuc HandlingPRO Tips  appeared first on DMC, Inc..

One of Actin’s advantages is its compatibility with many different types of robots. One feature I found particularly useful when using the SDK to control a non-traditional robotic device was the ability to define custom link kinematics. While Actin has standard link kinematics (such as prismatic or rotational) implemented, my task required an oval track joint where the robot would travel along an oval-shaped track. Fortunately, the Actin SDK provides a general base class, EcLinkKinematics, that can be used to implement custom link kinematics.

In this blog post, I will demonstrate how to use EcLinkKinematics by implementing a circle track joint class.

The Base Class, EcLinkKinematics

A custom link kinematic class is derived from Actin’s base class EcLinkKinematics, which can support any definable joint type with 1 degree of freedom.

#ifndef ecLinkKinematics_H_
#define ecLinkKinematics_H_
//------------------------------------------------------------------------------
// Copyright (c) 2003-2013 Energid Technologies. All rights reserved.
//
/// @file ecLinkKinematics.h
/// @class EcLinkKinematics
/// @brief Holds a description of a base class for link motion.
//
//------------------------------------------------------------------------------
#include <actinCore/actinCore_config.h>  // Required to be first header.
#include <xml/ecBaseExpTreeElement.h>
#include <foundCommon/ecCoordSysXForm.h>
#include <foundCommon/ecGeneralMotion.h>

// forward declarations
class EcArticulatedBodyDynamics;
class EcArticulatedBodyInertia;
class EcGeneralForce;
class EcJointActuator;

/// Holds a description of a base class for link motion. It supports general joint types 
/// with one degree of freedom.
class EC_ACTINCORE_MANIPULATOR_DECL EcLinkKinematics : public EcBaseExpressionTreeElement
{
public:
   /// unit type enumeration
   enum {LINEAR, ANGULAR, OTHER};

   /// default constructor - should not be used
   EcLinkKinematics ();

   /// destructor
   virtual ~EcLinkKinematics ();

   /// copy constructor
   EcLinkKinematics (const EcLinkKinematics& orig);

   /// assignment operator
   EcLinkKinematics& operator= (const EcLinkKinematics& orig);

   /// equality operator
   EcBoolean operator== (const EcLinkKinematics& orig) const;

   /// register components in this class
   virtual void registerComponents ();

   /// test for approximate equality
   virtual EcBoolean approxEq (const EcLinkKinematics& dh2, EcReal tol) const;

   /// kinematics functions

	/// get Primary Frame, which is the primary frame for the link represented in the
	/// link's DH frame

   /**
	\return The primary frame for this link. 
	This frame is used to specify physical extent, mass properties, and end effectors.
   */
   virtual const EcCoordinateSystemTransformation& primaryFrame () const;

   /// get Primary Frame Inverse
   virtual const EcCoordinateSystemTransformation& primaryFrameInverse () const;

   /// set Primary Frame
   virtual void setPrimaryFrame (const EcCoordinateSystemTransformation& value);

   /// calculate transformation
   /**
   \param[in] jointValue The joint value used to calculate the link transformation.
   \return The link transformation at jointValue.
   */
   virtual const EcCoordinateSystemTransformation& calculateTransform
      (
      EcReal jointValue
      ) const=0;

   /// transform an inboard transformation to the link's frame
   /**
   \param[in,out] xform The output transformation which is
	xform*calculateTransform(jointValue).
   \param[in] jointValue The joint value used to calculate the transformation.
   */
   virtual void transformBy
      (
      EcCoordinateSystemTransformation& xform,
      EcReal jointValue
      ) const=0;

   ///  get the general motion of the frame (locally represented).
   /**
	The default frame velocity calculation. 
	The velocity is the relative speed of the current frame to the parent frame
	represented in the current frame.  The default method will do a differentiation of
	the transformation, which is not as accurate if the close form solution of the frame
	velocity can be implemented in the child class.
   \param[in] jointValue The joint value.
   \param[in] jointVelocity The joint velocity.
   */
   virtual const EcGeneralMotion& calculateVelocity
      (
      EcReal jointValue,
      EcReal jointVelocity
      ) const;

   ///  get the general acceleration of the frame (locally represented).
   /**
	The default frame velocity calculation. The acceleration is the relative acceleration
	of the current frame to the parent frame represented in the current frame.  The
	default method will do a differentiation of the velocity, which is not as accurate if
	the close form solution of the frame acceleration can be implemented in the child
	class.
   \param[in] jointValue The joint value.
   \param[in] jointVelocity The joint velocity.
   \param[in] jointAcceleration The joint acceleration.
   */
   virtual const EcGeneralAcceleration& calculateAcceleration
      (
      EcReal jointValue,
      EcReal jointVelocity,
      EcReal jointAcceleration
      ) const;

   /// get the torque required to produce a unit acceleration of an
   /// articulated rigid body
   /**
   \param[in] jointValue The joint value.
   \param[in] inertia The articulated body inertia attached to the link.
   \return The torque required to produce a unit acceleration.
   */
   virtual EcReal unitAccelerationTorque
      (
      EcReal jointValue,
      const EcArticulatedBodyInertia& inertia
      ) const;

   /// get the torque required to exert the specified general force
   /**
   \param[in] jointValue The joint value.
   \param[in] exertedGeneralForce The desired general force.
   \return The torque required to exert the desired force.
   */
   virtual EcReal torqueRequiredToExert
      (
      EcReal jointValue,
      const EcGeneralForce& exertedGeneralForce
      ) const;

   /// compute an upper-bound distance between this DH
   /// and the parent
   virtual EcReal upperBoundDhFrameDistance
      (
      const EcJointActuator& jointActuator
      )const=0;

   /// add child arbd to parent's arbd
   virtual EcBoolean addChildArbdToParent
      (
      EcArticulatedBodyDynamics& parentArbd,
      const EcArticulatedBodyDynamics& childArbd,
      const EcReal jointValue,
      const EcReal jointTorque,
      const EcReal effectiveMotorInertia
      ) const;

   /// scale the kinematics by the specified distance-scale value
   /// (scaleFactor=1.0 does not change the object)
   virtual void scaleBy (EcReal scaleFactor)=0;

   /// transform this by a general coordinate system transformation.  This
   /// transformation is inserted before the link placement.  If the
   /// kinematics class has a precursor P, the P=XForm*P;
   virtual void transformBy (const EcCoordinateSystemTransformation& xform)=0;

   /// return the scale factor for the joint parameter (=1 for
   /// a distance-based parameter, 0 for non-distance-based)
   virtual EcReal jointParameterScalability ()const=0;

   /// change the inboard frame by an offset.
   /// This is to account for uncertainty in link measurements, both linear and angular.
   /// If offset is identity, then this does nothing.
   virtual void changeInboardFrameBy (const EcCoordinateSystemTransformation& offset)=0;

   /// return the unit type of the link kinematics (joint).
   virtual EcU32 unitType () const=0;

protected:

   /// the primary frame for the link represented in the link's DH frame
   EcCoordinateSystemTransformation m_PrimaryFrame;

   /// non-XML data below

   /// the inverse of the primary frame for the link represented in the link's DH frame
   /// this is stored for easy access
   EcCoordinateSystemTransformation m_PrimaryFrameInverse;

   /// a value for the transformation
   mutable EcCoordinateSystemTransformation m_FrameTransform;

   /// a value for the frame velocity
   mutable EcGeneralMotion m_FrameVelocity;

   /// a value for the frame Acceleration
   mutable EcGeneralAcceleration m_FrameAcceleration;

   // temporary variables for speed
   mutable EcGeneralMotion m_GMotion0;    /// First utility EcGeneralMotion
   mutable EcGeneralMotion m_GMotion1;    /// Second utility EcGeneralMotion
   mutable EcGeneralMotion m_GMotion2;    /// Third utility EcGeneralMotion
   /// First utility EcCoordinateSystemTransformation
   mutable EcCoordinateSystemTransformation m_XForm0;
      /// Second utility EcCoordinateSystemTransformation
   mutable EcCoordinateSystemTransformation m_XForm1;
};

#endif // ecLinkKinematics_H_

#ifndef ecLinkKinematics_H_
#define ecLinkKinematics_H_
//------------------------------------------------------------------------------
// Copyright (c) 2003-2013 Energid Technologies. All rights reserved.
//
/// @file ecLinkKinematics.h
/// @class EcLinkKinematics
/// @brief Holds a description of a base class for link motion.
//
//------------------------------------------------------------------------------
#include <actinCore/actinCore_config.h>  // Required to be first header.
#include <xml/ecBaseExpTreeElement.h>
#include <foundCommon/ecCoordSysXForm.h>
#include <foundCommon/ecGeneralMotion.h>

// forward declarations
class EcArticulatedBodyDynamics;
class EcArticulatedBodyInertia;
class EcGeneralForce;
class EcJointActuator;

/// Holds a description of a base class for link motion. It supports general joint types 
/// with one degree of freedom.
class EC_ACTINCORE_MANIPULATOR_DECL EcLinkKinematics : public EcBaseExpressionTreeElement
{
public:
   /// unit type enumeration
   enum {LINEAR, ANGULAR, OTHER};

   /// default constructor - should not be used
   EcLinkKinematics ();

   /// destructor
   virtual ~EcLinkKinematics ();

   /// copy constructor
   EcLinkKinematics (const EcLinkKinematics& orig);

   /// assignment operator
   EcLinkKinematics& operator= (const EcLinkKinematics& orig);

   /// equality operator
   EcBoolean operator== (const EcLinkKinematics& orig) const;

   /// register components in this class
   virtual void registerComponents ();

   /// test for approximate equality
   virtual EcBoolean approxEq (const EcLinkKinematics& dh2, EcReal tol) const;

   /// kinematics functions

	/// get Primary Frame, which is the primary frame for the link represented in the
	/// link's DH frame

   /**
	\return The primary frame for this link. 
	This frame is used to specify physical extent, mass properties, and end effectors.
   */
   virtual const EcCoordinateSystemTransformation& primaryFrame () const;

   /// get Primary Frame Inverse
   virtual const EcCoordinateSystemTransformation& primaryFrameInverse () const;

   /// set Primary Frame
   virtual void setPrimaryFrame (const EcCoordinateSystemTransformation& value);

   /// calculate transformation
   /**
   \param[in] jointValue The joint value used to calculate the link transformation.
   \return The link transformation at jointValue.
   */
   virtual const EcCoordinateSystemTransformation& calculateTransform
      (
      EcReal jointValue
      ) const=0;

   /// transform an inboard transformation to the link's frame
   /**
   \param[in,out] xform The output transformation which is
	xform*calculateTransform(jointValue).
   \param[in] jointValue The joint value used to calculate the transformation.
   */
   virtual void transformBy
      (
      EcCoordinateSystemTransformation& xform,
      EcReal jointValue
      ) const=0;

   ///  get the general motion of the frame (locally represented).
   /**
	The default frame velocity calculation. 
	The velocity is the relative speed of the current frame to the parent frame
	represented in the current frame.  The default method will do a differentiation of
	the transformation, which is not as accurate if the close form solution of the frame
	velocity can be implemented in the child class.
   \param[in] jointValue The joint value.
   \param[in] jointVelocity The joint velocity.
   */
   virtual const EcGeneralMotion& calculateVelocity
      (
      EcReal jointValue,
      EcReal jointVelocity
      ) const;

   ///  get the general acceleration of the frame (locally represented).
   /**
	The default frame velocity calculation. The acceleration is the relative acceleration
	of the current frame to the parent frame represented in the current frame.  The
	default method will do a differentiation of the velocity, which is not as accurate if
	the close form solution of the frame acceleration can be implemented in the child
	class.
   \param[in] jointValue The joint value.
   \param[in] jointVelocity The joint velocity.
   \param[in] jointAcceleration The joint acceleration.
   */
   virtual const EcGeneralAcceleration& calculateAcceleration
      (
      EcReal jointValue,
      EcReal jointVelocity,
      EcReal jointAcceleration
      ) const;

   /// get the torque required to produce a unit acceleration of an
   /// articulated rigid body
   /**
   \param[in] jointValue The joint value.
   \param[in] inertia The articulated body inertia attached to the link.
   \return The torque required to produce a unit acceleration.
   */
   virtual EcReal unitAccelerationTorque
      (
      EcReal jointValue,
      const EcArticulatedBodyInertia& inertia
      ) const;

   /// get the torque required to exert the specified general force
   /**
   \param[in] jointValue The joint value.
   \param[in] exertedGeneralForce The desired general force.
   \return The torque required to exert the desired force.
   */
   virtual EcReal torqueRequiredToExert
      (
      EcReal jointValue,
      const EcGeneralForce& exertedGeneralForce
      ) const;

   /// compute an upper-bound distance between this DH
   /// and the parent
   virtual EcReal upperBoundDhFrameDistance
      (
      const EcJointActuator& jointActuator
      )const=0;

   /// add child arbd to parent's arbd
   virtual EcBoolean addChildArbdToParent
      (
      EcArticulatedBodyDynamics& parentArbd,
      const EcArticulatedBodyDynamics& childArbd,
      const EcReal jointValue,
      const EcReal jointTorque,
      const EcReal effectiveMotorInertia
      ) const;

   /// scale the kinematics by the specified distance-scale value
   /// (scaleFactor=1.0 does not change the object)
   virtual void scaleBy (EcReal scaleFactor)=0;

   /// transform this by a general coordinate system transformation.  This
   /// transformation is inserted before the link placement.  If the
   /// kinematics class has a precursor P, the P=XForm*P;
   virtual void transformBy (const EcCoordinateSystemTransformation& xform)=0;

   /// return the scale factor for the joint parameter (=1 for
   /// a distance-based parameter, 0 for non-distance-based)
   virtual EcReal jointParameterScalability ()const=0;

   /// change the inboard frame by an offset.
   /// This is to account for uncertainty in link measurements, both linear and angular.
   /// If offset is identity, then this does nothing.
   virtual void changeInboardFrameBy (const EcCoordinateSystemTransformation& offset)=0;

   /// return the unit type of the link kinematics (joint).
   virtual EcU32 unitType () const=0;

protected:

   /// the primary frame for the link represented in the link's DH frame
   EcCoordinateSystemTransformation m_PrimaryFrame;

   /// non-XML data below

   /// the inverse of the primary frame for the link represented in the link's DH frame
   /// this is stored for easy access
   EcCoordinateSystemTransformation m_PrimaryFrameInverse;

   /// a value for the transformation
   mutable EcCoordinateSystemTransformation m_FrameTransform;

   /// a value for the frame velocity
   mutable EcGeneralMotion m_FrameVelocity;

   /// a value for the frame Acceleration
   mutable EcGeneralAcceleration m_FrameAcceleration;

   // temporary variables for speed
   mutable EcGeneralMotion m_GMotion0;    /// First utility EcGeneralMotion
   mutable EcGeneralMotion m_GMotion1;    /// Second utility EcGeneralMotion
   mutable EcGeneralMotion m_GMotion2;    /// Third utility EcGeneralMotion
   /// First utility EcCoordinateSystemTransformation
   mutable EcCoordinateSystemTransformation m_XForm0;
      /// Second utility EcCoordinateSystemTransformation
   mutable EcCoordinateSystemTransformation m_XForm1;
};

#endif // ecLinkKinematics_H_

The Mathematical Model – The Transformation for the Circle Joint

At the heart of link kinematics is the equation that defines the transformation from the inner frame to the outer frame using a single joint angle parameter. In Actin, the inner frame is rigidly attached to the parent link, while the outer frame is rigidly attached to the link’s physical extent. A frame is a coordinate system which defines a position and orientation, and a transformation defines the conversion between frames. In Actin, both concepts are represented through the EcCoordinateSystemTransformation class.

For our example, let the inner frame sit in the center of the circle, while the outer frame will travel along the circle’s perimeter while pointing its X-axis towards the center. The joint angle parameter will be the linear distance traveled along the circle’s perimeter. This transformation is defined in the transformBy method as shown below.

/////////////////////////////////////////////////////////////////////////
// Function:     transformBy
// Description:  transform an inboard transformation to the link's frame
//               The output is xform*FrameTrans(jointValue).
/////////////////////////////////////////////////////////////////////////
void CircleJoint::transformBy
(
	EcCoordinateSystemTransformation& xform,     // transformation
	EcReal jointValue                            	 // joint value
) const
{

	EcOrientation orientation;
	EcVector translation;

	// set to the precursor.
	xform *= precursor();

	translation.setX(m_Radius*cos(jointValue/m_Radius));
	translation.setY(m_Radius*sin(jointValue/m_Radius));
	translation.setZ(0);

	orientation.setFrom123Euler(0, 0, jointValue / m_Radius);

	// multiply by the transformation
	xform.outboardTransformBy(translation, orientation);
}

/////////////////////////////////////////////////////////////////////////
// Function:     transformBy
// Description:  transform an inboard transformation to the link's frame
//               The output is xform*FrameTrans(jointValue).
/////////////////////////////////////////////////////////////////////////
void CircleJoint::transformBy
(
	EcCoordinateSystemTransformation& xform,     // transformation
	EcReal jointValue                            	 // joint value
) const
{

	EcOrientation orientation;
	EcVector translation;

	// set to the precursor.
	xform *= precursor();

	translation.setX(m_Radius*cos(jointValue/m_Radius));
	translation.setY(m_Radius*sin(jointValue/m_Radius));
	translation.setZ(0);

	orientation.setFrom123Euler(0, 0, jointValue / m_Radius);

	// multiply by the transformation
	xform.outboardTransformBy(translation, orientation);
}

In this method definition, there is a reference to the precursor member variable, which is a transformation that occurs before the link kinematic’s transformation. Without the precursor, this joint would always rotate about the inner frame’s Z-axis and move on the XY plane. However, with the precursor, this joint can rotate about a different axis. For example, to rotate about the Y-axis, the precursor transformation can be set to a 90° rotation about the X-axis.

The velocity and acceleration methods do not need to be defined explicitly, as Actin can automatically calculate them discretely, but they can be implemented for efficiency as shown below.

/////////////////////////////////////////////////////////////////////////
// Function:     calculateVelocity
// Description:  Returns a general velocity calculated from the joint 
//				 value and joint velocity
/////////////////////////////////////////////////////////////////////////
const EcGeneralMotion&
CircleJoint::calculateVelocity
(
	EcReal jointValue,
	EcReal jointVelocity
) const
{

	m_FrameVelocity.setLinearX(-jointVelocity * sin(jointValue / m_Radius));
	m_FrameVelocity.setLinearY(jointVelocity*cos(jointValue / m_Radius));
	m_FrameVelocity.setLinearZ(0);

	m_FrameVelocity.setAngular(EcVector(0, 0, jointVelocity / m_Radius));

	return m_FrameVelocity;
}

/////////////////////////////////////////////////////////////////////////
// Function:     calculateAcceleration
// Description:  Returns a general acceleration calculated from the joint 
//				 value, joint velocity, and joint acceleration
/////////////////////////////////////////////////////////////////////////
const EcGeneralAcceleration&
CircleJoint::calculateAcceleration
(
	EcReal jointValue,
	EcReal jointVelocity,
	EcReal jointAcceleration
) const
{

	m_FrameAcceleration.setLinearX(-jointAcceleration * sin(jointValue / m_Radius)
		- pow(jointVelocity, 2) / m_Radius * cos(jointValue / m_Radius));
	m_FrameAcceleration.setLinearY(jointAcceleration*cos(jointValue / m_Radius)
		- pow(jointVelocity, 2) / m_Radius * sin(jointValue / m_Radius));
	m_FrameAcceleration.setLinearZ(0);

	m_FrameAcceleration.setAngular(EcVector(0, 0, jointAcceleration / m_Radius));

	return m_FrameAcceleration;
}

/////////////////////////////////////////////////////////////////////////
// Function:     calculateVelocity
// Description:  Returns a general velocity calculated from the joint 
//				 value and joint velocity
/////////////////////////////////////////////////////////////////////////
const EcGeneralMotion&
CircleJoint::calculateVelocity
(
	EcReal jointValue,
	EcReal jointVelocity
) const
{

	m_FrameVelocity.setLinearX(-jointVelocity * sin(jointValue / m_Radius));
	m_FrameVelocity.setLinearY(jointVelocity*cos(jointValue / m_Radius));
	m_FrameVelocity.setLinearZ(0);

	m_FrameVelocity.setAngular(EcVector(0, 0, jointVelocity / m_Radius));

	return m_FrameVelocity;
}

/////////////////////////////////////////////////////////////////////////
// Function:     calculateAcceleration
// Description:  Returns a general acceleration calculated from the joint 
//				 value, joint velocity, and joint acceleration
/////////////////////////////////////////////////////////////////////////
const EcGeneralAcceleration&
CircleJoint::calculateAcceleration
(
	EcReal jointValue,
	EcReal jointVelocity,
	EcReal jointAcceleration
) const
{

	m_FrameAcceleration.setLinearX(-jointAcceleration * sin(jointValue / m_Radius)
		- pow(jointVelocity, 2) / m_Radius * cos(jointValue / m_Radius));
	m_FrameAcceleration.setLinearY(jointAcceleration*cos(jointValue / m_Radius)
		- pow(jointVelocity, 2) / m_Radius * sin(jointValue / m_Radius));
	m_FrameAcceleration.setLinearZ(0);

	m_FrameAcceleration.setAngular(EcVector(0, 0, jointAcceleration / m_Radius));

	return m_FrameAcceleration;
}

XML Methods: Saving and Loading the Custom Link Kinematics

The EcLinkKinematics class derives from Actin’s EcXmlCompoundType, which has built-in XML functionality. This allows Actin to read and write our custom link kinematics class to an XML file, which Actin uses to save its models. Without this functionality, we would have to re-add the custom link kinematics to an Actin model file every time we load it.

For the member variables that must be saved to the XML file (in this example, the circle radius and precursor frame), XML tags need to be defined through the EcToken class (which holds a tag and a namespace), as shown in the header file below. These tokens are used by Actin’s XML parser to identify the data.

#ifndef CircleJointTokens_H_
#define CircleJointTokens_H_

#include <xml/ecToken.h>

namespace CircleJointNamespace
{
	const EcString NS = " CircleJointNamespace#";

	// Elements
	const EcToken CircleJointToken = NS + "CircleJoint";
	const EcToken CircleJointPrecursor = NS + "CircleJointPrecursor";
	const EcToken CircleJointRadiusToken = NS + "CircleJointRadius";

}

#endif // CircleJointTokens_H_

#ifndef CircleJointTokens_H_
#define CircleJointTokens_H_

#include <xml/ecToken.h>

namespace CircleJointNamespace
{
	const EcString NS = " CircleJointNamespace#";

	// Elements
	const EcToken CircleJointToken = NS + "CircleJoint";
	const EcToken CircleJointPrecursor = NS + "CircleJointPrecursor";
	const EcToken CircleJointRadiusToken = NS + "CircleJointRadius";

}

#endif // CircleJointTokens_H_

The member variable tokens are then registered using the registerComponents method.

/////////////////////////////////////////////////////////////////////////
// Functions:    registerComponents()
// Description:  registers all the components for this class that are
//               read and written to XML files.
/////////////////////////////////////////////////////////////////////////
void CircleJoint::registerComponents()
{
	// call parent
	EcLinkKinematics::registerComponents();

	registerComponent(CircleJointPrecursor, &m_Precursor);
	registerComponent(CircleJointRadiusToken, &m_Radius);
}

/////////////////////////////////////////////////////////////////////////
// Functions:    registerComponents()
// Description:  registers all the components for this class that are
//               read and written to XML files.
/////////////////////////////////////////////////////////////////////////
void CircleJoint::registerComponents()
{
	// call parent
	EcLinkKinematics::registerComponents();

	registerComponent(CircleJointPrecursor, &m_Precursor);
	registerComponent(CircleJointRadiusToken, &m_Radius);
}

The class token can be defined using the ECXML_DEFINE_TOKENS macro.

ECXML_DEFINE_TOKENS(CircleJoint, CircleJointNamespace::CircleJointToken)

ECXML_DEFINE_TOKENS(CircleJoint, CircleJointNamespace::CircleJointToken)

Actin can now read and write the class to an XML file, as shown below.

 <mynamespace:circlejoint library="CircleJoint.ecp" xmlns:mynamespace="MyNameSpace">
  <mynamespace:circlejointprecursor>
    <cr:orientation q0=".7071067811865476" q1=".7071067811865475" q2="-0" q3="0" xmlns:cr="http://www.energid.com/namespace/cr">
    <translation x="0" y="0" z="0">
  </translation></cr:orientation></mynamespace:circlejointprecursor>
  <mynamespace:circlejointradius>2</mynamespace:circlejointradius>
  <primaryframe>
    <cr:orientation q0="1" q1="0" q2="0" q3="0" xmlns:cr="http://www.energid.com/namespace/cr">
    <translation x="0" y="0" z="0">
  </translation></cr:orientation></primaryframe>
</mynamespace:circlejoint>

 <mynamespace:circlejoint library="CircleJoint.ecp" xmlns:mynamespace="MyNameSpace">
  <mynamespace:circlejointprecursor>
    <cr:orientation q0=".7071067811865476" q1=".7071067811865475" q2="-0" q3="0" xmlns:cr="http://www.energid.com/namespace/cr">
    <translation x="0" y="0" z="0">
  </translation></cr:orientation></mynamespace:circlejointprecursor>
  <mynamespace:circlejointradius>2</mynamespace:circlejointradius>
  <primaryframe>
    <cr:orientation q0="1" q1="0" q2="0" q3="0" xmlns:cr="http://www.energid.com/namespace/cr">
    <translation x="0" y="0" z="0">
  </translation></cr:orientation></primaryframe>
</mynamespace:circlejoint>

The primaryFrame data is inherited from the base EcLinkKinematics class and used as a general reference for all links in Actin. Link parameters such as mass properties are defined relative to this frame.

Creating an XML Object Library – Loading the Custom Link Kinematics in ActinViewer

To avoid always including the source code, the custom link kinematics can be saved as a library. This library can also be used by ActinViewer (which is Energid’s Actin GUI Interface) to load and display the custom link kinematics. To save the library using Actin’s build system, we must define a libraryAttribute method.

EcXmlObject* CircleJoint::libraryAttribute()
{
	m_LibraryAttribute = "CircleJoint.ecp";
	return &m_LibraryAttribute;
}

EcXmlObject* CircleJoint::libraryAttribute()
{
	m_LibraryAttribute = "CircleJoint.ecp";
	return &m_LibraryAttribute;
}

The custom kinematics can be built into a library using Actin’s CMake macros.

ecProject(CircleJoint)

ecIncludeSolutions(
	stableFoundation
	foundation
	actinCore
	actin
)

ecExternIncludeDirs(Boost)

ecProjectLinkLibraries(
	actinCore - foundCommon
	stableFoundation - xmlReaderWriter
)

ecSourceFiles(
	CircleJoint.cpp
)

ecXmlObjectLibraryAndPlugin(
	CircleJoint
)

ecProject(CircleJoint)

ecIncludeSolutions(
	stableFoundation
	foundation
	actinCore
	actin
)

ecExternIncludeDirs(Boost)

ecProjectLinkLibraries(
	actinCore - foundCommon
	stableFoundation - xmlReaderWriter
)

ecSourceFiles(
	CircleJoint.cpp
)

ecXmlObjectLibraryAndPlugin(
	CircleJoint
)

When built, this will generate a libecCircleJoint.so file.

Adding the Custom Link Kinematics into a Manipulator

Since our custom link kinematics is not part of the ActinViewer interface, we have to add it to a manipulator programmatically. This can be accomplished by defining a CircleJoint class and setting it as the link kinematics to the desired manipulator link.

//Create a manipulator link object
EcManipulatorLink link;

//Define our custom kinematics
CircleJoint cj;
cj.setRadius(2);
EcOrientation ori;
ori.setFrom123Euler(EcPi / 2, 0, 0);
EcCoordinateSystemTransformation xform;
xform.setOrientation(ori);
cj.setPrecursor(xform);

//Set as the link's kinematics
link.setLinkKinematics(cj);

//Create a manipulator link object
EcManipulatorLink link;

//Define our custom kinematics
CircleJoint cj;
cj.setRadius(2);
EcOrientation ori;
ori.setFrom123Euler(EcPi / 2, 0, 0);
EcCoordinateSystemTransformation xform;
xform.setOrientation(ori);
cj.setPrecursor(xform);

//Set as the link's kinematics
link.setLinkKinematics(cj);

When compiling this code, the Circle Joint library must be linked through the ecProjectLinkLibraries CMake macro.

ecProjectLinkLibraries(examples-CircleJoint)

ecProjectLinkLibraries(examples-CircleJoint)

I created the circle joint as a project within Actin’s examples solution (solutions are declared by the ecSolution() CMake macro), but the general form to this macro is ecProjectLinkLibraries(<solution name>-<project name>).

Complete Class

The above instructions summarize the basic steps to create a custom link kinematics in the Actin SDK. Included below is the full Circle Joint code.

Tokens Header File

// ----------------------------------------------------------------------------------
// Company: DMC
// Engineer: Sophia Dolan
//
// Create Date: 8/2017
// Module Name: CircleJoint – circleJointTokens.h
// Project Name: Example Custom Link Kinematics
// Description: A link kinematics that represents a circular track joint
// ----------------------------------------------------------------------------------

#ifndef CircleJointTokens_H_
#define CircleJointTokens_H_

#include <xml/ecToken.h>

namespace CircleJointNamespace
{
    const EcString NS = "CircleJointNamespace#";

    // Elements
    const EcToken CircleJointToken        = NS + "CircleJoint";
    const EcToken CircleJointPrecursor    = NS + "CircleJointPrecursor";
    const EcToken CircleJointRadiusToken  = NS + "CircleJointRadius";
}

#endif // CircleJointTokens_H_

// ----------------------------------------------------------------------------------
// Company: DMC
// Engineer: Sophia Dolan
//
// Create Date: 8/2017
// Module Name: CircleJoint – circleJointTokens.h
// Project Name: Example Custom Link Kinematics
// Description: A link kinematics that represents a circular track joint
// ----------------------------------------------------------------------------------

#ifndef CircleJointTokens_H_
#define CircleJointTokens_H_

#include <xml/ecToken.h>

namespace CircleJointNamespace
{
    const EcString NS = "CircleJointNamespace#";

    // Elements
    const EcToken CircleJointToken        = NS + "CircleJoint";
    const EcToken CircleJointPrecursor    = NS + "CircleJointPrecursor";
    const EcToken CircleJointRadiusToken  = NS + "CircleJointRadius";
}

#endif // CircleJointTokens_H_

Class Header File

// ----------------------------------------------------------------------------------
// Company: DMC
// Engineer: Sophia Dolan
//
// Create Date : 08/2017
// Module Name : CircleJoint
// File Name   : ecCircleJoint.h
// Project     : Example Custom Link Kinematics
// Description :
//     A custom link kinematics implementation that represents a
//     circular track joint.
// ----------------------------------------------------------------------------------

#ifndef EC_CIRCLEJOINT_H_
#define EC_CIRCLEJOINT_H_

#include <actinCore/actinCore_config.h>      // Must be included first
#include <foundCommon/ecCoordSysXForm.h>
#include <manipulator/ecJointActuator.h>
#include <manipulator/ecLinkKinematics.h>
#include <xml/ecXmlVectorType.h>

/// A joint that follows a geometrically defined circular rail.
class EC_ACTINCORE_MANIPULATOR_DECL CircleJoint : public EcLinkKinematics
{
   EC_XMLOBJECT_PLUGIN_DECLARE(CircleJoint);

public:

   /// Initialize XML components for serialization.
   virtual EcBoolean xmlInit();

   /// Register XML components with the parent object.
   virtual void registerComponents();

   /// Factory method.
   static EcXmlObject* creator();

   /// Get precursor transformation.
   virtual const EcCoordinateSystemTransformation& precursor() const;

   /// Set precursor transformation.
   virtual void setPrecursor(
      const EcCoordinateSystemTransformation& value
   );

   /// Get circular track radius (meters).
   EcReal radius() const;

   /// Set circular track radius.
   void setRadius(EcReal radius);

   /// Calculate the D-H transformation for the supplied joint value.
   virtual const EcCoordinateSystemTransformation& calculateTransform(
      EcReal jointValue
   ) const;

   /// Transform an inboard transformation to the link's D-H frame.
   /// Result:
   ///
   ///     xform = xform * DH(jointValue)
   ///
   virtual void transformBy(
      EcCoordinateSystemTransformation& xform,
      EcReal jointValue
   ) const;

   /// Calculate joint velocity.
   virtual const EcGeneralMotion& calculateVelocity(
      EcReal jointValue,
      EcReal jointVelocity
   ) const;

   /// Calculate joint acceleration.
   virtual const EcGeneralAcceleration& calculateAcceleration(
      EcReal jointValue,
      EcReal jointVelocity,
      EcReal jointAcceleration
   ) const;

   using EcLinkKinematics::approxEq;

   /// Test for approximate equality.
   virtual EcBoolean approxEq(
      const CircleJoint& other,
      EcReal tolerance
   ) const;

   /// Compute the upper-bound D-H frame distance for this joint.
   virtual EcReal upperBoundDhFrameDistance(
      const EcJointActuator& jointActuator
   ) const;

   /// Scale the kinematics by the specified factor.
   ///
   /// scaleFactor = 1.0 leaves the object unchanged.
   virtual void scaleBy(EcReal scaleFactor);

   /// Apply a coordinate transformation before link placement.
   ///
   /// For precursor P:
   ///
   ///     P = xform * P
   ///
   virtual void transformBy(
      const EcCoordinateSystemTransformation& xform
   );

   /// Return the parameter scalability factor.
   ///
   /// Returns:
   ///   1.0 for distance-based parameters
   ///   0.0 for non-distance-based parameters
   ///
   virtual EcReal jointParameterScalability() const;

   /// Modify the inboard frame by an offset transformation.
   ///
   /// Used to account for uncertainty in link measurements,
   /// both translational and rotational.
   virtual void changeInboardFrameBy(
      const EcCoordinateSystemTransformation& offset
   );

   /// Read object from XML.
   virtual EcBoolean read(EcXmlReader& stream);

   /// Write object to XML.
   virtual EcBoolean write(EcXmlWriter& stream) const;

   /// Return a default/empty object.
   static CircleJoint nullObject();

   /// Return unit type identifier.
   virtual EcU32 unitType() const;

   /// Run internal validation tests.
   EcBoolean selfTest() const;

private:

   /// Precursor transformation.
   EcCoordinateSystemTransformation m_Precursor;

   /// Radius of the circular track.
   EcXmlReal m_Radius;

   /// Cached joint value associated with the stored transform.
   mutable EcReal m_JointValueForStoredTransform;
};

#endif // EC_CIRCLEJOINT_H_

// ----------------------------------------------------------------------------------
// Company: DMC
// Engineer: Sophia Dolan
//
// Create Date : 08/2017
// Module Name : CircleJoint
// File Name   : ecCircleJoint.h
// Project     : Example Custom Link Kinematics
// Description :
//     A custom link kinematics implementation that represents a
//     circular track joint.
// ----------------------------------------------------------------------------------

#ifndef EC_CIRCLEJOINT_H_
#define EC_CIRCLEJOINT_H_

#include <actinCore/actinCore_config.h>      // Must be included first
#include <foundCommon/ecCoordSysXForm.h>
#include <manipulator/ecJointActuator.h>
#include <manipulator/ecLinkKinematics.h>
#include <xml/ecXmlVectorType.h>

/// A joint that follows a geometrically defined circular rail.
class EC_ACTINCORE_MANIPULATOR_DECL CircleJoint : public EcLinkKinematics
{
   EC_XMLOBJECT_PLUGIN_DECLARE(CircleJoint);

public:

   /// Initialize XML components for serialization.
   virtual EcBoolean xmlInit();

   /// Register XML components with the parent object.
   virtual void registerComponents();

   /// Factory method.
   static EcXmlObject* creator();

   /// Get precursor transformation.
   virtual const EcCoordinateSystemTransformation& precursor() const;

   /// Set precursor transformation.
   virtual void setPrecursor(
      const EcCoordinateSystemTransformation& value
   );

   /// Get circular track radius (meters).
   EcReal radius() const;

   /// Set circular track radius.
   void setRadius(EcReal radius);

   /// Calculate the D-H transformation for the supplied joint value.
   virtual const EcCoordinateSystemTransformation& calculateTransform(
      EcReal jointValue
   ) const;

   /// Transform an inboard transformation to the link's D-H frame.
   /// Result:
   ///
   ///     xform = xform * DH(jointValue)
   ///
   virtual void transformBy(
      EcCoordinateSystemTransformation& xform,
      EcReal jointValue
   ) const;

   /// Calculate joint velocity.
   virtual const EcGeneralMotion& calculateVelocity(
      EcReal jointValue,
      EcReal jointVelocity
   ) const;

   /// Calculate joint acceleration.
   virtual const EcGeneralAcceleration& calculateAcceleration(
      EcReal jointValue,
      EcReal jointVelocity,
      EcReal jointAcceleration
   ) const;

   using EcLinkKinematics::approxEq;

   /// Test for approximate equality.
   virtual EcBoolean approxEq(
      const CircleJoint& other,
      EcReal tolerance
   ) const;

   /// Compute the upper-bound D-H frame distance for this joint.
   virtual EcReal upperBoundDhFrameDistance(
      const EcJointActuator& jointActuator
   ) const;

   /// Scale the kinematics by the specified factor.
   ///
   /// scaleFactor = 1.0 leaves the object unchanged.
   virtual void scaleBy(EcReal scaleFactor);

   /// Apply a coordinate transformation before link placement.
   ///
   /// For precursor P:
   ///
   ///     P = xform * P
   ///
   virtual void transformBy(
      const EcCoordinateSystemTransformation& xform
   );

   /// Return the parameter scalability factor.
   ///
   /// Returns:
   ///   1.0 for distance-based parameters
   ///   0.0 for non-distance-based parameters
   ///
   virtual EcReal jointParameterScalability() const;

   /// Modify the inboard frame by an offset transformation.
   ///
   /// Used to account for uncertainty in link measurements,
   /// both translational and rotational.
   virtual void changeInboardFrameBy(
      const EcCoordinateSystemTransformation& offset
   );

   /// Read object from XML.
   virtual EcBoolean read(EcXmlReader& stream);

   /// Write object to XML.
   virtual EcBoolean write(EcXmlWriter& stream) const;

   /// Return a default/empty object.
   static CircleJoint nullObject();

   /// Return unit type identifier.
   virtual EcU32 unitType() const;

   /// Run internal validation tests.
   EcBoolean selfTest() const;

private:

   /// Precursor transformation.
   EcCoordinateSystemTransformation m_Precursor;

   /// Radius of the circular track.
   EcXmlReal m_Radius;

   /// Cached joint value associated with the stored transform.
   mutable EcReal m_JointValueForStoredTransform;
};

#endif // EC_CIRCLEJOINT_H_

Class Implementation File

// ----------------------------------------------------------------------------------
// Company: DMC
// Engineer: Sophia Dolan
//
// Create Date : 08/2017
// Module      : CircleJoint
// File        : circleJoint.cpp
// Project     : Example Custom Link Kinematics
// Description :
//     Custom link kinematics representing a circular track joint.
// ----------------------------------------------------------------------------------

#include "circleJoint.h"
#include "circleJointTokens.h"

#include <foundCore/ecMacros.h>
#include <foundCore/ecMath.h>
#include <manipulator/ecJointActuator.h>
#include <manipulator/ecManipulatorTokens.h>
#include <math.h>
#include <xmlReaderWriter/ecXmlObjectReaderWriter.h>

using namespace CircleJointNamespace;

ECXML_DEFINE_TOKENS(
    CircleJoint,
    CircleJointNamespace::CircleJointToken
)

EcXmlObject* CircleJoint::libraryAttribute()
{
    m_LibraryAttribute = "CircleJoint.ecp";
    return &m_LibraryAttribute;
}

//------------------------------------------------------------------------------
// Constructors / Destructor
//------------------------------------------------------------------------------

CircleJoint::CircleJoint() :
    EcLinkKinematics(),
    m_Precursor(EcCoordinateSystemTransformation::nullObject()),
    m_Radius(3.0),
    m_JointValueForStoredTransform(0.0)
{
}

CircleJoint::~CircleJoint()
{
}

CircleJoint::CircleJoint(const CircleJoint& other) :
    EcLinkKinematics(other),
    m_Precursor(other.m_Precursor),
    m_Radius(other.m_Radius),
    m_JointValueForStoredTransform(other.m_JointValueForStoredTransform)
{
}

CircleJoint& CircleJoint::operator=(const CircleJoint& other)
{
    if (this == &other)
    {
        return *this;
    }

    EcLinkKinematics::operator=(other);

    m_Precursor = other.m_Precursor;
    m_Radius = other.m_Radius;
    m_JointValueForStoredTransform =
        other.m_JointValueForStoredTransform;

    return *this;
}

EcBoolean CircleJoint::operator==(const CircleJoint& other) const
{
    return
        EcLinkKinematics::operator==(other) &&
        m_Precursor == other.m_Precursor &&
        m_Radius == other.m_Radius;
}

//------------------------------------------------------------------------------
// XML Support
//------------------------------------------------------------------------------

EcXmlObject* CircleJoint::creator()
{
    return new CircleJoint();
}

EcBoolean CircleJoint::xmlInit()
{
    return EcLinkKinematics::xmlInit();
}

void CircleJoint::registerComponents()
{
    EcLinkKinematics::registerComponents();

    registerComponent(
        CircleJointPrecursor,
        &m_Precursor
    );

    registerComponent(
        CircleJointRadiusToken,
        &m_Radius
    );
}

//------------------------------------------------------------------------------
// Accessors
//------------------------------------------------------------------------------

const EcCoordinateSystemTransformation&
CircleJoint::precursor() const
{
    return m_Precursor;
}

void CircleJoint::setPrecursor(
    const EcCoordinateSystemTransformation& value
)
{
    m_Precursor = value;
}

EcReal CircleJoint::radius() const
{
    return m_Radius;
}

void CircleJoint::setRadius(EcReal radius)
{
    m_Radius = radius;
}

//------------------------------------------------------------------------------
// Kinematics
//------------------------------------------------------------------------------

const EcCoordinateSystemTransformation&
CircleJoint::calculateTransform(
    EcReal jointValue
) const
{
    m_JointValueForStoredTransform = jointValue;

    m_FrameTransform.setToIdentity();

    transformBy(
        m_FrameTransform,
        m_JointValueForStoredTransform
    );

    return m_FrameTransform;
}

void CircleJoint::transformBy(
    EcCoordinateSystemTransformation& xform,
    EcReal jointValue
) const
{
    EcOrientation orientation;
    EcVector translation;

    xform *= precursor();

    const EcReal angle = jointValue / m_Radius;

    translation.setX(
        m_Radius * cos(angle)
    );

    translation.setY(
        m_Radius * sin(angle)
    );

    translation.setZ(0.0);

    orientation.setFrom123Euler(
        0.0,
        0.0,
        angle
    );

    xform.outboardTransformBy(
        translation,
        orientation
    );
}

//------------------------------------------------------------------------------
// Velocity / Acceleration
//------------------------------------------------------------------------------

const EcGeneralMotion&
CircleJoint::calculateVelocity(
    EcReal jointValue,
    EcReal jointVelocity
) const
{
    const EcReal angle = jointValue / m_Radius;

    m_FrameVelocity.setLinearX(
        -jointVelocity * sin(angle)
    );

    m_FrameVelocity.setLinearY(
         jointVelocity * cos(angle)
    );

    m_FrameVelocity.setLinearZ(0.0);

    m_FrameVelocity.setAngular(
        EcVector(
            0.0,
            0.0,
            jointVelocity / m_Radius
        )
    );

    return m_FrameVelocity;
}

const EcGeneralAcceleration&
CircleJoint::calculateAcceleration(
    EcReal jointValue,
    EcReal jointVelocity,
    EcReal jointAcceleration
) const
{
    const EcReal angle = jointValue / m_Radius;
    const EcReal velocitySquared =
        jointVelocity * jointVelocity;

    m_FrameAcceleration.setLinearX(
        -jointAcceleration * sin(angle)
        - velocitySquared / m_Radius * cos(angle)
    );

    m_FrameAcceleration.setLinearY(
         jointAcceleration * cos(angle)
        - velocitySquared / m_Radius * sin(angle)
    );

    m_FrameAcceleration.setLinearZ(0.0);

    m_FrameAcceleration.setAngular(
        EcVector(
            0.0,
            0.0,
            jointAcceleration / m_Radius
        )
    );

    return m_FrameAcceleration;
}

//------------------------------------------------------------------------------
// Utility Functions
//------------------------------------------------------------------------------

EcBoolean CircleJoint::approxEq(
    const CircleJoint& other,
    EcReal tol
) const
{
    const EcBoolean parentEqual =
        EcLinkKinematics::approxEq(
            other,
            tol
        );

    const EcBoolean frameEqual =
        primaryFrame().approxEq(
            other.primaryFrame(),
            tol
        );

    const EcBoolean radiusEqual =
        fabs(m_Radius - other.radius()) <
        fabs(tol);

    return
        parentEqual &&
        frameEqual &&
        radiusEqual;
}

void CircleJoint::scaleBy(
    EcReal scaleFactor
)
{
    m_Precursor.setTranslation(
        m_Precursor.translation() *
        scaleFactor
    );

    m_Radius *= scaleFactor;
}

void CircleJoint::transformBy(
    const EcCoordinateSystemTransformation& xform
)
{
    m_Precursor =
        xform * m_Precursor;
}

EcReal CircleJoint::jointParameterScalability() const
{
    return 1.0;
}

//------------------------------------------------------------------------------
// XML Read / Write
//------------------------------------------------------------------------------

EcBoolean CircleJoint::read(
    EcXmlReader& stream
)
{
    EcBoolean result =
        EcXmlCompoundType::read(stream);

    m_PrimaryFrameInverse =
        m_PrimaryFrame.inverse();

    return result;
}

EcBoolean CircleJoint::write(
    EcXmlWriter& stream
) const
{
    return EcXmlCompoundType::write(stream);
}

//------------------------------------------------------------------------------
// Miscellaneous
//------------------------------------------------------------------------------

CircleJoint CircleJoint::nullObject()
{
    return CircleJoint();
}

EcU32 CircleJoint::unitType() const
{
    return LINEAR;
}

EcReal CircleJoint::upperBoundDhFrameDistance(
    const EcJointActuator& jointActuator
) const
{
    return EcMath::maximum(
        calculateTransform(
            jointActuator.upperLimit()
        ).translation().mag(),

        calculateTransform(
            jointActuator.lowerLimit()
        ).translation().mag()
    );
}

void CircleJoint::changeInboardFrameBy(
    const EcCoordinateSystemTransformation& offset
)
{
    m_Precursor *= offset;
}

//------------------------------------------------------------------------------
// Self Test
//------------------------------------------------------------------------------

EcBoolean CircleJoint::selfTest() const
{
    CircleJoint original;
    original.setRadius(200.0);

    const EcString filename =
        "CircleJointSelfTest.xml";

    EcXmlObjectReaderWriter::writeToFile(
        original,
        filename
    );

    CircleJoint loaded;

    EcXmlObjectReaderWriter::readFromFile(
        loaded,
        filename
    );

    if (!(original == loaded))
    {
        EcPrint(Error)
            << "CircleJoint self-test failed"
            << std::endl;

        return EcFalse;
    }

    return EcTrue;
}

// ----------------------------------------------------------------------------------
// Company: DMC
// Engineer: Sophia Dolan
//
// Create Date : 08/2017
// Module      : CircleJoint
// File        : circleJoint.cpp
// Project     : Example Custom Link Kinematics
// Description :
//     Custom link kinematics representing a circular track joint.
// ----------------------------------------------------------------------------------

#include "circleJoint.h"
#include "circleJointTokens.h"

#include <foundCore/ecMacros.h>
#include <foundCore/ecMath.h>
#include <manipulator/ecJointActuator.h>
#include <manipulator/ecManipulatorTokens.h>
#include <math.h>
#include <xmlReaderWriter/ecXmlObjectReaderWriter.h>

using namespace CircleJointNamespace;

ECXML_DEFINE_TOKENS(
    CircleJoint,
    CircleJointNamespace::CircleJointToken
)

EcXmlObject* CircleJoint::libraryAttribute()
{
    m_LibraryAttribute = "CircleJoint.ecp";
    return &m_LibraryAttribute;
}

//------------------------------------------------------------------------------
// Constructors / Destructor
//------------------------------------------------------------------------------

CircleJoint::CircleJoint() :
    EcLinkKinematics(),
    m_Precursor(EcCoordinateSystemTransformation::nullObject()),
    m_Radius(3.0),
    m_JointValueForStoredTransform(0.0)
{
}

CircleJoint::~CircleJoint()
{
}

CircleJoint::CircleJoint(const CircleJoint& other) :
    EcLinkKinematics(other),
    m_Precursor(other.m_Precursor),
    m_Radius(other.m_Radius),
    m_JointValueForStoredTransform(other.m_JointValueForStoredTransform)
{
}

CircleJoint& CircleJoint::operator=(const CircleJoint& other)
{
    if (this == &other)
    {
        return *this;
    }

    EcLinkKinematics::operator=(other);

    m_Precursor = other.m_Precursor;
    m_Radius = other.m_Radius;
    m_JointValueForStoredTransform =
        other.m_JointValueForStoredTransform;

    return *this;
}

EcBoolean CircleJoint::operator==(const CircleJoint& other) const
{
    return
        EcLinkKinematics::operator==(other) &&
        m_Precursor == other.m_Precursor &&
        m_Radius == other.m_Radius;
}

//------------------------------------------------------------------------------
// XML Support
//------------------------------------------------------------------------------

EcXmlObject* CircleJoint::creator()
{
    return new CircleJoint();
}

EcBoolean CircleJoint::xmlInit()
{
    return EcLinkKinematics::xmlInit();
}

void CircleJoint::registerComponents()
{
    EcLinkKinematics::registerComponents();

    registerComponent(
        CircleJointPrecursor,
        &m_Precursor
    );

    registerComponent(
        CircleJointRadiusToken,
        &m_Radius
    );
}

//------------------------------------------------------------------------------
// Accessors
//------------------------------------------------------------------------------

const EcCoordinateSystemTransformation&
CircleJoint::precursor() const
{
    return m_Precursor;
}

void CircleJoint::setPrecursor(
    const EcCoordinateSystemTransformation& value
)
{
    m_Precursor = value;
}

EcReal CircleJoint::radius() const
{
    return m_Radius;
}

void CircleJoint::setRadius(EcReal radius)
{
    m_Radius = radius;
}

//------------------------------------------------------------------------------
// Kinematics
//------------------------------------------------------------------------------

const EcCoordinateSystemTransformation&
CircleJoint::calculateTransform(
    EcReal jointValue
) const
{
    m_JointValueForStoredTransform = jointValue;

    m_FrameTransform.setToIdentity();

    transformBy(
        m_FrameTransform,
        m_JointValueForStoredTransform
    );

    return m_FrameTransform;
}

void CircleJoint::transformBy(
    EcCoordinateSystemTransformation& xform,
    EcReal jointValue
) const
{
    EcOrientation orientation;
    EcVector translation;

    xform *= precursor();

    const EcReal angle = jointValue / m_Radius;

    translation.setX(
        m_Radius * cos(angle)
    );

    translation.setY(
        m_Radius * sin(angle)
    );

    translation.setZ(0.0);

    orientation.setFrom123Euler(
        0.0,
        0.0,
        angle
    );

    xform.outboardTransformBy(
        translation,
        orientation
    );
}

//------------------------------------------------------------------------------
// Velocity / Acceleration
//------------------------------------------------------------------------------

const EcGeneralMotion&
CircleJoint::calculateVelocity(
    EcReal jointValue,
    EcReal jointVelocity
) const
{
    const EcReal angle = jointValue / m_Radius;

    m_FrameVelocity.setLinearX(
        -jointVelocity * sin(angle)
    );

    m_FrameVelocity.setLinearY(
         jointVelocity * cos(angle)
    );

    m_FrameVelocity.setLinearZ(0.0);

    m_FrameVelocity.setAngular(
        EcVector(
            0.0,
            0.0,
            jointVelocity / m_Radius
        )
    );

    return m_FrameVelocity;
}

const EcGeneralAcceleration&
CircleJoint::calculateAcceleration(
    EcReal jointValue,
    EcReal jointVelocity,
    EcReal jointAcceleration
) const
{
    const EcReal angle = jointValue / m_Radius;
    const EcReal velocitySquared =
        jointVelocity * jointVelocity;

    m_FrameAcceleration.setLinearX(
        -jointAcceleration * sin(angle)
        - velocitySquared / m_Radius * cos(angle)
    );

    m_FrameAcceleration.setLinearY(
         jointAcceleration * cos(angle)
        - velocitySquared / m_Radius * sin(angle)
    );

    m_FrameAcceleration.setLinearZ(0.0);

    m_FrameAcceleration.setAngular(
        EcVector(
            0.0,
            0.0,
            jointAcceleration / m_Radius
        )
    );

    return m_FrameAcceleration;
}

//------------------------------------------------------------------------------
// Utility Functions
//------------------------------------------------------------------------------

EcBoolean CircleJoint::approxEq(
    const CircleJoint& other,
    EcReal tol
) const
{
    const EcBoolean parentEqual =
        EcLinkKinematics::approxEq(
            other,
            tol
        );

    const EcBoolean frameEqual =
        primaryFrame().approxEq(
            other.primaryFrame(),
            tol
        );

    const EcBoolean radiusEqual =
        fabs(m_Radius - other.radius()) <
        fabs(tol);

    return
        parentEqual &&
        frameEqual &&
        radiusEqual;
}

void CircleJoint::scaleBy(
    EcReal scaleFactor
)
{
    m_Precursor.setTranslation(
        m_Precursor.translation() *
        scaleFactor
    );

    m_Radius *= scaleFactor;
}

void CircleJoint::transformBy(
    const EcCoordinateSystemTransformation& xform
)
{
    m_Precursor =
        xform * m_Precursor;
}

EcReal CircleJoint::jointParameterScalability() const
{
    return 1.0;
}

//------------------------------------------------------------------------------
// XML Read / Write
//------------------------------------------------------------------------------

EcBoolean CircleJoint::read(
    EcXmlReader& stream
)
{
    EcBoolean result =
        EcXmlCompoundType::read(stream);

    m_PrimaryFrameInverse =
        m_PrimaryFrame.inverse();

    return result;
}

EcBoolean CircleJoint::write(
    EcXmlWriter& stream
) const
{
    return EcXmlCompoundType::write(stream);
}

//------------------------------------------------------------------------------
// Miscellaneous
//------------------------------------------------------------------------------

CircleJoint CircleJoint::nullObject()
{
    return CircleJoint();
}

EcU32 CircleJoint::unitType() const
{
    return LINEAR;
}

EcReal CircleJoint::upperBoundDhFrameDistance(
    const EcJointActuator& jointActuator
) const
{
    return EcMath::maximum(
        calculateTransform(
            jointActuator.upperLimit()
        ).translation().mag(),

        calculateTransform(
            jointActuator.lowerLimit()
        ).translation().mag()
    );
}

void CircleJoint::changeInboardFrameBy(
    const EcCoordinateSystemTransformation& offset
)
{
    m_Precursor *= offset;
}

//------------------------------------------------------------------------------
// Self Test
//------------------------------------------------------------------------------

EcBoolean CircleJoint::selfTest() const
{
    CircleJoint original;
    original.setRadius(200.0);

    const EcString filename =
        "CircleJointSelfTest.xml";

    EcXmlObjectReaderWriter::writeToFile(
        original,
        filename
    );

    CircleJoint loaded;

    EcXmlObjectReaderWriter::readFromFile(
        loaded,
        filename
    );

    if (!(original == loaded))
    {
        EcPrint(Error)
            << "CircleJoint self-test failed"
            << std::endl;

        return EcFalse;
    }

    return EcTrue;
}

Learn more about DMC’s Robotic Automation and Integration services. Or, contact us to get started on a project today.

The post Implementing Custom Link Kinematics in Energid’s Actin SDK appeared first on DMC, Inc..

To prove to myself that it could not have been an issue of technological limitations (and to have an excuse to play with a Cognex camera, ABB’s RobotStudio, and the Star Wars toys I keep on my desk), I decided to spin up a quick tutorial to show that I could, in fact, locate and retrieve the droid I was looking for.

RobotStudio Integrated Vision

The ABB RobotStudio’s “Integrated Vision” feature is essentially a “Cognex In-Sight Lite,” and as of publication, this is only functional on the 32-bit version of robot studio.

To access the Integrated Vision tab, expand your robot controller (physical or virtual) in the left-hand controller pane and right-click on the Vision System item. Right-clicking will open the Integrated Vision tab of RobotStudio.

Connecting to the Camera

Connect the camera to the robot controller service port switch. Once connected, the camera should appear under Vision System in the left-hand controller tree.

If not, then from the vision tab, select Connect/Add Senor. In this window, you should be able to see all cameras physically connected to the network and can change network settings of the cameras accordingly.

If you are connecting a camera (or an emulated camera) to a virtual robot controller, you will need to define the virtual programming port of the virtual controller to which the camera is connecting.

To do so, find the vc_network_definition.xml file in the RobotStudio/Systems/Controller Name/Home/IV folder. In this XML file, set the IP Address/Subnet to that of the NIC connected to the camera.

Warm restart the virtual controller you are using, and an unconfigured camera should appear under Vision System in the system tree.

Calibration

Now that the camera is connected, you need to calibrate the images from the camera to real-world units of measurement (pixels to millimeters). The easiest way to do this is with the grid calibration method.

To do so, select the Calibrate button from the top ribbon, then select Grid from the Calibration Type drop-down in the context menu. Selecting grid will pull up the configuration options for the grid calibration sizing.

Verify the selection of Checkerboard, with fiducial for the grid type. The other options can be left as is (see below).

The only option that may need adjustment would be the lens model. Select radial for straight-on pictures (for example, top-down) view, or choose projection if the camera is not parallel with the target object (for example, being mounted perpendicular to it).

Once the grid parameters have been set up, select Print Grid to print off a copy of the grid.

Verify the spacing of the checkers on the grid matches the selection in the previous view.

Center the grid within the field of view of the camera, and tape it in place (it’ll be important later that the grid does not move after the calibration image has been taken).

Once in place, select Next in the context menu with the grid setup, and then select Acquire Image within the context menu.

Once the image has been acquired, and the camera can recognize the calibration image, select the Calibrate button to load the calibration data into the active camera job. If the camera does not recognize the calibration image, it may require adjusting the camera position, exposure, or focus.

Now that the camera is calibrated, you will need to align the origin and orientation of the camera image (defined by the location of the fiducial in the calibration grid), with a workobject defined in the robot.

To do so, using a defined calibration pointing tool, define the camera workobject along the same X/Y axis as is on the taped calibration grid (only calibrate the user frame, as the object frame will then be used to shift the coordinate system to move to identified objects). At this point, the camera and robot workobject coordinate systems should be aligned.

Identifying Part Location

Once the camera and robot are calibrated, you can begin setting up your part location tools to locate your target objects. Several tools are available in the Add Part Location Tool menu, all of which will report back part location (X,Y coordinate) and orientation (for brevity’s sake, I won’t discuss the individual configuration of each tool).

Once a location tool has been selected and configured to locate the desired part, the next step is configuring the output parameters to the robot RAPID program.

To do so, select the Output to Rapid button at the top, which will open the Setup Communication context menu. Using this menu, you can define which parameters (Result) of which tools (Group) you want to reference in the RAPID program.

At a minimum, you should send the Fixture.X, Fixture.Y, Fixture.Angle, and Pass or Fail parameters (I’ve also included the Fixture.Score parameter for reference to show how closely the tool models match the captured images).

RAPID Configuration

Once the vision job has been set up and calibrated, and the camera workobject has been defined to align coordinate systems with the camera, the actual part identification/movement can be done.

Using one of the out-of-the-box code snippets available in RobotStudio as a starting point (RAPID/Snippet/Integrated Vision), set up a procedure to execute a camera job. After the job is complete, set the camera object frame to be vision coordinates of the camera result.

  PROC MoveToDetectedObject()
      
      VAR cameratarget mycameratarget;
      VAR wobjdata mywobj;
      VAR tooldata mytool; 
      VAR robtarget myrobtarget;
      VAR string myjob := "myjob.job";
      
      CamSetProgramMode RobotCamera;
      CamLoadJob RobotCamera, myjob;
      CamSetRunMode RobotCamera;
      
      CamReqImage RobotCamera;
      CamGetResult RobotCamera, mycameratarget;
      mywobj.oframe := mycameratarget.cframe;
      
      !During the first cycle, run the program until this point,
      !then jog the tool to the desired grip position and modpos myrobtarget.
      MoveL myrobtarget, v100, fine, mytool \WObj:=mywobj;
  ENDPROC

  PROC MoveToDetectedObject()
      
      VAR cameratarget mycameratarget;
      VAR wobjdata mywobj;
      VAR tooldata mytool; 
      VAR robtarget myrobtarget;
      VAR string myjob := "myjob.job";
      
      CamSetProgramMode RobotCamera;
      CamLoadJob RobotCamera, myjob;
      CamSetRunMode RobotCamera;
      
      CamReqImage RobotCamera;
      CamGetResult RobotCamera, mycameratarget;
      mywobj.oframe := mycameratarget.cframe;
      
      !During the first cycle, run the program until this point,
      !then jog the tool to the desired grip position and modpos myrobtarget.
      MoveL myrobtarget, v100, fine, mytool \WObj:=mywobj;
  ENDPROC

In the example above, the VAR declarations are only shown for clarity, and should most likely be declared in the user module. Additionally, if only one job is being used, the camera job can be loaded (CamLoadJob) in a startup routine to cut down on job cycle time.

To align the position of the targeted object identified by the camera to a robot position (for example, a pick or place position), you will need to run the procedure you created above through the point where the object frame of the workobject is loaded with the location data from the camera.

What this will do is align the robot position you are about to teach to be relative to both the location of the camera coordinate system (defined by the calibration procedure above), as well as the recognized position of the target object within the coordinate system.

You can now jog the robot to the desired position, being sure that the correct workobject and tool are loaded that will be used in your sequence, and save the position. Now, the position of the robot is defined as being relative to the identified position of the object, allowing the robot to consistently track the location and orientation of the object as it moves in the camera coordinate system.

Example

In the pictures below, you can see how the camera is able to track the location and orientation of BB8 as he moves to various locations along a wall in our lab. To do so, I first created a part location tool called BB8_Finder. I chose to search just for his head, as I thought that would be the best way to find a consistent location and orientation for BB8.

Pictured below is the reference picture used by the inspection tool, which looks like a BB8 mugshot.

Once I had my tool configured, I took a few shots of BB8 in different positions and orientations to verify that I could successfully track his movement (and for the record, that is “The Force” holding BB8 in place and definitely not tape…). In the tables below, you can see the camera tracking the position and orientation of BB8 in each of the pictures (the origin is located in the top-left of the picture).

Conclusion

You should now be able to track down and retrieve any droids you are looking for. 

Learn more about DMC’s Machine Vision Inspection and Integration Services. 

The post ABB Vision-Guided Movement – These ARE the Droids You’re Looking For appeared first on DMC, Inc..

$SCR.$coldovrd

Long answer:

The robot's done. Testing went perfectly, operators know how to start, stop, and reset the system from the HMI without ever needing to touch the Teach Pendant. Then, someone powers off the robot to do some maintenance and notices the robot is now unusually slow on powerup. You get a phone call and want to tell them just to use the speed adjustment keys on the Teach Pendant after they power cycle the robot. However, you're a little uneasy that something else might go wrong if the Teach Pendant can't stay locked behind a cabinet's doors. You either drive to the site to follow these steps, or work remotely with someone at the robot with this guide.

Note: Depending on the robot system you're using, the screens and menus might look different. 

1. You have a backup of the robot, right? If not, back it up!
2. Stop the robot, ensure it's ok to be unavailable for 15 minutes.
3. Perform a Controlled Start: Turn the robot off, then turn it back on while holding the PREV and NEXT buttons until you see it started a Controlled Start.

   

   

4.  
5. Press [MENU] and select "4 Variables."

   

6. Scroll to $SCR and open it (used Shift+Arrow to move down faster).

   

7. Scroll to $COLDOVRD within $SCR and enter in the new speed.

   

8. Cold start the robot: Press [FCTN] and then select "1 START (COLD)."

   

9.  
10. Notice the robot speed is now what you specified as $COLDOVRD. If it didn't go to that speed, power cycle the robot once. If it still isn't going to the $COLDOVRD speed after a power cycle, check the parameter again and contact FANUC if you still have issues.

    

Flexibility

If you want more flexibility, you can use Override Select (Menu, Setup, Override Select) which lets you define 4 configurable override speeds that are selected from digital inputs (from a PLC, hardwired inputs, etc.).

Safety

Be aware that the reason for 10% speed on startup is for safety. You don't want a robot running at 100% speed after someone turned the robot off, added a bunch of breakable dishes in front of the robot, and turned the robot back on. But, if you can ensure that the robot will always be safe running at the $COLDOVRD speed after any cold start, you and your robot should be good to go!

Learn more about DMC's robotic automation services.

The post How to Change a Fanuc Robot’s Default Speed on Cold Start appeared first on DMC, Inc..

Here are just some of the projects DMC employees worked on this FedEx Day. 

DMC Boston

Bike SmartLights – Frank May

Frank’s car indicates with lights when he hits the brakes, and some cooler cars have lights that turn on when you walk up to the car. Frank wanted his bike to do the same, so he spent the day collaborating with the design firm Altitude getting the core functionality of this working while enjoying getting to ride his bike around the office.
Learn more about this project.

DMC Hydroponics – Phil Schaffer, Jirka Hladis, and Eric Baggen

Phil, Jirka, and Eric B. designed and built a hydroponics system with a time-lapse camera to grow various types of flowers to exponentially increase Zen in DMC Boston. The setup relies on a custom-made Ebb & Flow System, continuously flooding and draining water, which removes the need for an additional aeration system.

DMC Chicago

Model Train – Gina Zak

Gina set up an N-scale model train set to run along the quad. The project is just in its beginning phases with wiring the track, power supply, and model building lights. Eventually, they’d like to have the train run all the way around their quad with automated bridges!       

 
​​​​​​
Cooking for Colleagues – Smoked Meat, Mac n’ Cheese, Cornbread and Coleslaw – Patrick Corcoran, Spencer Glesmann, Grant Anderson, Molly Graham, Amy Costello, Heather Talbert, Elisha Harris, John Toljanic, Courtney Mitchell

Patrick and Spencer took the lead planning a follow-up to the Cooking for Colleagues initiative that our President Frank Riordan kicked off at the last FedEx Day.

For this FedEx Day, Patrick and Spencer pulled out all the stops and planned a smoked meat feast that included brisket and pork butt, coleslaw, cornbread muffins, and 50 lbs. of mac n’ cheese. They worked tirelessly overnight using Patrick’s smoker to prepare the meat in DMC’s parking lot. It took lots of mini-teams to pull everything together, but it was more than worth the labor. 

Between the meat, the mac n’ cheese, the coleslaw, and the cornbread, there was enough food to feed everyone for lunch on FedEx day… and again on Friday when we all met to review our completed projects.

Ping Pong Demo – Beth Reinert

Beth spent FedEx day continuing to rework the ping pong demo, which uses LabVIEW to play solo. She focused on ensuring the demo correctly locates the ball’s current position, predicts the ball’s path accurately, and actuates the solenoid at the correct time to hit the ball.

Custom Tap Handles – Nikhil Holay, Jeff McCormick, David Sestrich, Ken Brey

Nikhil, Jeff, David, and Ken built engraved wooden tap handles for our kegerator. They used Fusion 360 for the CAD modeling/G-code generation, and the X-Carve in our office lab for the actual cutting.

DMC Ping Pong App – Jordan Harris and Curtis Weir

DMC’s ping pong app uses a GoPro to record pong sessions and ranks players by their wins and losses. Curtis and Jordan worked on replacing the old GoPro Hero3 with a new GoPro Hero5 Session camera. They also updated the replay capture code on the Ping Pong App to use the new camera and upload replays to YouTube.

We all look forward to more crazy ping pong shots being caught on camera!

DMC Rooftop Garden – Anne Patterson, Jimmy Brady, Deborah Nunaley, Heather Talbert, Lexi Torres, Molly Graham, Natalie Meeker, Alex Krejcie, Matt Goedke

The DMC rooftop garden is turning five this year, and the garden crew spent part of the day prepping the soil for planting in May. An additional team worked to update the automatic watering system’s moisture detection.  

Monitoring Moisture and Repairing the Auto Watering System

Natalie and Alex used Power BI to work on moisture content detection.There is a wi-fi chip that ARM’s embedded IoT platform uses to talk to Azure and Azure talks to us. This allows the watering system to track moisture over time, keep the plants happy with water as they need it, and prevents accidental flooding of the garden and the roof!

Unfortunately, it won’t water the office dogs, but they did check out the roof while everyone worked on the garden.


 

DMC Denver

RF Chamber – Boris Cherkasskiy

The aim of this project was to create a basic RF test lab to perform rough FCC pre-pre-compliance (not an official term) validation at the DMC office before committing to the full test at an external lab. The team built and tested a portable/collapsible RF semi-anechoic enclosure, utilizing nylon-based nickel/copper fabric and a removable lid with transparent mesh for an easy access and visual monitoring.

Drink Bot Project – Cameron Fyfe and Ross Bunker

Cameron and Ross worked on the Denver drink bot, a portable demo that utilizes Siemens hardware to mix drinks, similar to Boston’s Drinxperiment. This update for the drink bot included integrating Cortana. The Drink Bot will debut at the Siemens Automation Summit in June which will feature 5 DMC Presentations. 

DMC Houston

DMC Houston spent time making their office more beautiful following their recent office expansion.

DMC New York

Grocery App – Simon Healey and Liz Rapoport

Liz and Simon worked on a grocery app to make restocking the office kitchen faster and easier. To speed up the process, they wrote a WPF application that connects to a database with a list of their most ordered items and lets them select directly from the app. They just add items to the cart, then press one button which compiles the list and emails it to Cat, the Administrative Assistant in Boston.

Office Beautification

DMC New York also spent some time making their office space more organized and beautiful. They hung shelves and organized their lab. They also found a space to hang their college pennants!

FedEx Day is just one more reason DMC continues to be named one of Crain’s Best Places to Work in Chicago. 

The post Cooking Up New Ideas (and BBQ) at DMC’s FedEx Day appeared first on DMC, Inc..

Installation

First step is to install Visual Studio. Visual Studio Community is free and works perfectly for this application.

After installing Visual Studio, go through the PCDK installer. 

Getting Started with FANUC PCDK

Next, start up Visual Studio and create a new Console Application. I called mine “FanucTest”.

After clicking OK, right click on the “References” in the solution, and click “Add Reference”.

Under COM, find FANUC Robotics Controller Interface. Select it and click OK.

Now to begin writing code!

Connecting to a Robot

Add the following highlighted lines to your code to connect to your robot. If this runs, you’ve successfully installed PCDK and you’re ready to communicate with your robot. 

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using FRRobot;      //uses the robot reference we just added

namespace FanucTest
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();

            //Create a robot object
            FRCRobot mobjRobot = new FRCRobot();
            //Connect to your robot
            mobjRobot.Connect("192.168.1.123");
            bool connected = mobjRobot.IsConnected;

        }

    }
}

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using FRRobot;      //uses the robot reference we just added

namespace FanucTest
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();

            //Create a robot object
            FRCRobot mobjRobot = new FRCRobot();
            //Connect to your robot
            mobjRobot.Connect("192.168.1.123");
            bool connected = mobjRobot.IsConnected;

        }

    }
}

Updating a Position Register

To finish off this hello world program, add the following lines of code to update a position register. We’re accessing position register 1 below and updating the values. 

  //See help topics "Efficient Access to Positions"
            FRCSysPositions sysPositions = mobjRobot.RegPositions;
            FRCSysPosition sysPosition = sysPositions[1];
            FRCSysGroupPosition sysGroupPosition = sysPosition.Group[1];
            FRCXyzWpr xyzWpr = sysGroupPosition.Formats[FRETypeCodeConstants.frXyzWpr];
            //Prepare updated X,Y,Z,W,P, and R values of position register 1
            xyzWpr.X = 475;
            xyzWpr.Y = -275;
            xyzWpr.Z = -231;
            xyzWpr.W = -176;
            xyzWpr.P = 0;
            xyzWpr.R = 0;
            try
            {
                //Update position register 1
                sysGroupPosition.Update();

            }

  //See help topics "Efficient Access to Positions"
            FRCSysPositions sysPositions = mobjRobot.RegPositions;
            FRCSysPosition sysPosition = sysPositions[1];
            FRCSysGroupPosition sysGroupPosition = sysPosition.Group[1];
            FRCXyzWpr xyzWpr = sysGroupPosition.Formats[FRETypeCodeConstants.frXyzWpr];
            //Prepare updated X,Y,Z,W,P, and R values of position register 1
            xyzWpr.X = 475;
            xyzWpr.Y = -275;
            xyzWpr.Z = -231;
            xyzWpr.W = -176;
            xyzWpr.P = 0;
            xyzWpr.R = 0;
            try
            {
                //Update position register 1
                sysGroupPosition.Update();

            }

To learn how to do more with the robot, check out the PCDK help documentation. Depending on your version of Windows, you might need to install another program to view the help documentation. 

Learn more about DMC’s Manufacturing and Automation Intelligence services and contact us today!

The post How to Use FANUC PC Developer’s Kit (PCDK) appeared first on DMC, Inc..

Robots are complex systems with a lot of different parts. Ideally, the components of most complex systems should be modular and encapsulated. Each part should be able to function with minimal dependency on a different part. At the very core, that’s what ROS provides. Components of a robot, be it the vision system, the arms, or a microcontroller can be separated into nodes that communicate with each other through a common communication standard, called topics.

But that’s not all. Any component can talk to any other component because the sender sends the message packet in the format that the receiver would get, all managed by the master ROS node. So the only major requirement for integrating different parts of a robot is to make sure that the topics expected are the topics being sent. Suddenly, the need to make complex drivers for new systems is gone. Let your new component be a new node and make sure any messages it sends out is in a ROS topic. Now any other component should be able to recognize the topic and get information.

Suddenly, a roboticist somewhere writes some amazing computer vision software, and another roboticist on the other side of the world can easily integrate that software with the robot he already has. As you might expect, the power to collaborate has opened the way for open-source robotics software. Projects can be exported as packages, which function similarly to software libraries.

ROS is growing and growing. As development gets faster due to the abundance of software packages available online, more and more packages are added to the ever growing global ROS library. And more packages means that people have even more reasons to start using ROS in their own projects, projects get off the ground faster, and it becomes easier to do cool and crazy robotics stuff like controlling a robot’s head with an Oculus Rift.

Learn more about DMC's robotic automation and integration services.

The post The Robot Operating System: What is ROS? appeared first on DMC, Inc..