Actin 6.2.0 Release Notes

2021 March 30

Energid is pleased to present Actin 6.2.0.


New Features

Actin Viewer

Added an option to create an Empty Simulation file

Actin Viewer now allows the user to create an empty simulation file.

User can create a new simulation using the menu option - Hamburger menu -> File -> New or "New Simulation" button in the home page.

Actin Viewer Ribbon Toolbar Redesign

The tool and menu options for Actin Viewer have been reorganized into a Ribbon Tab. The Actin Viewer Ribbon Tabs are broken into four tabbed sections: View, Model, Control, and Simulation. Each tab contains groups and tool items. The redesigned interface has been given a dark theme with new icons.

Collision Detection

Added "EcBaseProximityTool::checkSystemCollision" method to check collision for the whole system

Previously, only EcBaseProximityTool::checkManipulatorCollision was provided to check collision for a single manipulator. To check collision for the whole system, one would have to call EcBaseProximityTool::checkManipulatorCollision in a loop for all manipulators in the system. EcBaseProximityTool::checkSystemCollision is more convenient and more efficient if one desires to check whether there is a collision within the system.

Extensions

Added control task and EcScript commands for admittance control

Provide a control task to calculate the admittance of a frame end effector given the external force-torque. Also add two EcScript commands to start and stop admittance calculation.

gRPC

Added new generic, multiplexed RPCs to Data Store gRPC Service

Previously, the Data Store gRPC Service provided a Get${TYPE}Value, Set${TYPE}Value, Read${TYPE}Stream, and Write${TYPE}Stream RPC for each supported data store element type. Each of these RPCs could only operate on a single data store element when invoked. The sheer number of these RPCs made the service API difficult to maintain and type-agnostic gRPC clients difficult to write.

This feature update has provided a new API to the Data Store gRPC Service that is both smaller and more functional than the old API. Data store element types are encoded within the message payloads themselves, allowing the same RPC to be used for all types. Each RPC in the new API supports operating on multiple data store elements simultaneously, even if those elements have differing types. The RPCs composing this API are the following:

  • GetSupportedTypes: gets list of data store element types supported by service
  • GetValues: reads current value of one or more data store elements
  • SetValues: set value of one or more data store elements
  • ReadValuesStream: open server stream to receive value updates for one or more data store elements
  • ConfigureValuesStream: expand, shrink, or close server stream previously opened by ReadValuesStream
  • WriteValuesStream: open client stream to write values to one or more data store elements

With this feature update, the old Data Store gRPC Service API (e.g. Get${TYPE}Value) has been marked deprecated, to be removed in a future Actin release.

Logging Framework

Added "utc" attribute to EcComplexLogSinkFactory

Previously, all timestamps in log messages were localtime. The "utc" attribute was added to EcComplexLogSinkFactory to provide the option to use Coordinated Universal Time instead.

The "utc" attribute is now available to use with the following sink factories:

  • EcConsoleSinkFactory
  • EcDistSinkFactory
  • EcFileSinkFactory
  • EcLevelFilterSinkFactory
  • EcNullSinkFactory
  • EcRotatingFileSinkFactory
  • EcActinFileSinkFactory

Added "dir" attribute to EcBaseFileSinkFactory

Previously, EcBaseFileSinkFactory did not have a dir (directory) attribute. EcActinFileSinkFactory had this attribute to allow creating log files in the Energid "app data directory" (~/.energid/). Other file output log sinks could make use of this, so the directory attribute was moved from EcActinFileSinkFactory to EcBaseFileSinkFactory.

The directory attribute can be configured with the following values:

  • ENERGID: Create the file in the Energid "app data directory"
  • CWD: Create the file in the current working directory

The directory attribute is now available to use with the following file sinks:

  • EcFileSinkFactory (default to CWD)
  • EcRotatingFileSinkFactory (default to CWD)
  • EcActinFileSinkFactory (default to ENERGID)

Motion Script

Added EcScript command "get_payload" to retrieve the link payload mass

The get_payload command returns the total or a certain payload mass of a link as a real value.

  • :real (get_payload <manip_index:u32> <link_index:u32>) returns the total payload mass of a certain link.
  • :real (get_payload <manip_index:u32> <link_index:u32> <payload_name:string>) returns the mass of a certain named payload.
  • Both will fail, if the desired items don't exist.

Add initializeLibrary entry point for control extensions

Add a new initializeLibrary() "C" entry point for control extensions. When the extension is loaded this entry point is called and can be used for static registration of types, motion script commands, etc.

Added EcScript command "stop_t" to stop an end effector within deadline

The stop_t command stops an end effector within a given deadline. The end effector must not be a joint end effector.

  • Command syntax: (stop_t <manip_index:u32> <ee_set_index:u32> <ee_index:u32> <deadline:real>).
  • The command will fail, if the inputs are invalid, or the end effector is a joint end effector.

Path Planning

Added Asynchronous RRT Path Planning

RRT path planning can now be performed asynchronously through the RCF framework. Previously, only synchronous RRT path planning could be performed

  • Added control task to perform path planning jobs
  • Supports queuing multiple jobs (FIFO processing)
  • Added motion scripts to trigger and query a path planning job

Improvements

Collision Avoidance

Added API that allows customers to replace our proximity tool with their own logic

API was added to allow customers to replace the proximity tool from EcExpressionCollisionAvoidanceAB with their own version.

Developer Diagnostics

Add function to query controller validity

Add the isValid() function to EcVelocityController to get a summary query of whether a controller has a valid configuration.

Expand usage of "static_assert" in interProcessCore and rtControl

Add more static_assert checks to verify correct base classes are being used with registration methods

Logging Framework

Added support for fmt::format style messages in EcRETURN_IF_ERROR_MSG and EcGET_FIRST_ERROR_MSG

Previously, complex messages had to be formatted as a string before being passed into the macros. EcRETURN_IF_ERROR_MSG( EcBaseRtControlObject::initializeImpl(dataAccessLayer), logTag(), fmt::format("Failed to initialize EnqueueDriveEnableTask ({})", dataStoreAbsolutePath()));

This improvement allows the messages to be formatted in the style of the fmt library, which also matches the format used for log messages. EcRETURN_IF_ERROR_MSG( EcBaseRtControlObject::initializeImpl(dataAccessLayer), logTag(), "Failed to initialize EnqueueDriveEnableTask ({})", dataStoreAbsolutePath());

This improvement was made to the following macros:

  • EcRETURN_IF_ERROR_MSG
  • EcGET_FIRST_ERROR_MSG

Added support for fmt::format style messages in throw macros

Previously, complex messages had to be formatted as a string before being passed into the throw macros. EcTHROW(std::out_of_range, "EcOrientation::operator[]: index " + EcINT2STRING(index) + " > 3");

This improvement allows the messages to be formatted in the style of the fmt library, which also matches the format used for log messages. EcTHROW(std::out_of_range, "EcOrientation::operator[]: index {} > 3", index);

This improvement was made to the following macros:

  • EcTHROW
  • EcTOGGLE_THROW

Motion Script

Extended EcScript command "find_solution" to support single end effector input

Previously, to calculate the joint solution of a manipulator, one had to provide all placements of a whole end effector set. Now, one can also only provide a single end effector placement to the command. And the current placement of the other end effectors will be used in the calculation.

  • Extended syntax: (find_solution <manip_index:u32> <ee_set_index:u32> <ee_index:u32> <solution_symbol:real_vec_symbol> <target_place:pose> ...).

Added File Name display in Motion Script Gui

The recently opened motion script file name is now displayed in the UI.

Position Control System

Added next-gen position control system

Added a next generation position control system. Key changes relative to the legacy position control system are:

  • Report state at end of timestep instead of start
  • Don't do double IK calcs when state has been updated externally (via setCurrentState)
  • Skip singularity checks (currently a necessary side effect of not doing double IK calcs)
  • Don't zero out velocity of uncontrolled manipulators

The existing functionality is mature but this API and behavior are both subject to significant change.

RCF

Added SWITCH_ON callback to cia402ServoSlave DataStoreConfig layer

The new SWITCH_ON callback will enable the Cia402 state machine to transit to a "Switched On" state from the "Switched On Disable" state. From this state, the Cia402 drive can be "Operation Enabled" by triggering the "Enable" operation.

Added an attribute shutdownTimeoutInMs to EcRtProcess

This attribute can be used to override the default shutdown timeout(100ms) for all threads to finish in EcRtProcess.


Deprecations

Variable deprecations

  • Deprecate EcFinitDifferenceTool::m_pSystemActiveState which was unused by Actin code
  • Remove forward declaration of class EcSystemActiveState; from manipulator/ecManipulatorLink.h
  • Remove forward declaration of class EcSystemActiveState; from control/ecErrorReductionFunction.h
  • Deprecate EcPositionControlSystem::m_MaxFinalPropagationSize which is only used as part of the already deprecated calculateState function
  • Deprecate EcPositionControlSystem::m_CheckCollisionsOnBothPasses which is only used as part of the already removed multiplass option

Deprecate "EcEndEffector::minimumTime" method

The EcEndEffector::minimumTime method, which is pure virtual, has been deprecated and will be removed in Actin 7.0 release. When it's removed, the classes derived from EcEndEffector method no longer have to implement the minimumTime method.


Resolved Issues

Over the course of this release we have resolved a large number of issues. We are including an overview of the highest profile issues that have been fixed for Actin 6.2.0.

  • QNX SDK fails to build the prometheusExample on the host machine
  • Make sure cmake dependency builds use toolchain file if specified
  • Fix the Qt5 issues in FindEcQt5.cmake
  • Missing MSVC runtime dependencies when installing on fresh systems
  • EC_BUILD_NUMBER is polluted as suffix by the cpack script
  • customOptimizationExample can't find data files on QNX
  • Return type const qualifier warnings in licenseCheck
  • Fix a warning of an uninitialized variable
  • Improve some numerical robustness issues in EcTrigonometricTrajectoryProfileTool
  • Fix warnings reported by Clang
  • Fix 32-bit compilation errors on Debian 10
  • EcScript should never return an error message on success
  • move_joint_seq fails in some cases when speed scaling is active
  • Scaling factors in EcSynchronizedJointInterpolationTool are using the wrong index
  • DSLC requires an active network connection for binding to a MAC address
  • Fix time scaling calculation with multiple joint groups

    Fixed a bug in the joint rate filter where the reported time scaling could be incorrect if the manipulator had multiple joint groups. This bug affected performance of motion scripts like move_linear that are time scaling aware.

  • Cone/cone collision avoidance is resulting in erratic motion
  • Cherry pick ethercatcommon gtest fix to actin_6.2
  • Fix findAcontis for QNX
  • Re-level logging in script executor
  • Change ECScript client connection log messages to debug
  • Fix QNX build for RRT control task
  • Replace deprecated ParseScript function in EcScriptExecutor
  • Script executor does not reset state on all stops
  • print_log motion script crashes when passed literal values
  • Possible deadlock in signal handling for actinRcf
  • System controller should zero out system time in loaded model files
  • Review thread-safety for g_pProcess in actinRcf
  • Data store service ignores WritesDone signal for write streams
  • Update cytonProfilingPoses version number
  • Autoload plugins preference
  • Update license tool to properly handle command line for trial licenses
  • Motion script gui text color change on mouse focus
  • Fix typos in EcModbus error messages
  • Actin Viewer crashes when changing shape color attributes
  • Dynamic collsion exclusion map not set from GUI as expected
  • 7zip missing from thirdparty library list in Actinviewer help about
  • Fix warnings printed by MotionScriptParseExample