FlexScan3D User Manual - Version 3.3.4.x

You are here: API/SDK and Automation > Rotary Plugin Module

Rotary Plugin Module

The plugin SDK is included with each FlexScan3D installation starting with release 3.3.2.x. The plugin is included in the directory C:\Program Files\LMI Technologies\FlexScan3D 3.3\SDK\PluginRotary by default.

Use the PluginRotaryCore project to implement the communication in C/C++. For C#, use the PluginRotaryWR project; this project implements the protocol described in the Rotary Protocol section.

Setup

You must develop your plugin using Visual Studio 2010 or later.

API

The following describes the API functions in general terms.

Required Functions

int PRC_BuildRotaryList()

Builds the list of all the available rotaries. This function is first called when FlexScan3D loads the rotary module.

The implementation should communicate with the actual rotary to determine if the rotary is connected.

In a multi-axis system, each axis should be represented as an independent motor within a rotary module.

Returns: The number of rotaries detected.

char* PRC_GetRotaryID(int index)

Gets the rotary name from the list of rotaries.

Parameters: index: Index of the rotary name to retrieve.
Returns: Unique rotary ID string. For example: "PluginRotaryABC::COM3", "PluginRotaryABC::IP:68.179.21.245", "PluginRotaryABC::MyRotary1".

BOOL PRC_IsConnected(const char* ID)

Determines if a rotary is connected.

Parameters: ID: Unique rotary ID string returned by PRC_GetRotaryID.
Returns: True if the function succeeds. False if the function fails.

BOOL PRC_GetNumMotors(const char* ID, int& motors)

Gets the number of motors or axes.

Parameters: ID: Unique ID string.; motors: Pointer to return the number of motors.
Returns: True if the function succeeds. False if the function fails.

BOOL PRC_GetCurrStep(const char* ID, int motor, int& step)

Gets the current step position.

Parameters: ID: Unique ID string.; motors: The number of motors.; step: The current step position. The value is between -StepsPerTurn to StepsPerTurn.
Returns: True if the function succeeds. False if the function fails.

BOOL PRC_GetStepsPerTurn(const char* ID, int motor, int& steps)

Gets the number of steps per one revolution (360 degree).

Parameters: ID: Unique ID string.; motors: Pointer to return the number of motors.; step: Pointer to return the number of steps per turn.
Returns: True if the function succeeds. False if the function fails. Returns 0 for displacement motors.

BOOL PRC_SetStepsPerTurn(const char* ID, int motor, int steps)

Sets the number of steps per one revolution (360 degree).

Parameters: ID: Unique ID string.; motors: Pointer to return the number of motors.; step: Number of steps per turn.
Returns: True if the function succeeds. False if the function fails.

BOOL PRC_Move(const char* ID, int motor, int steps)

Moves the motor forward by a fixed number of steps.

Parameters: ID: Unique ID string.; motors: Pointer to return the number of motors.; step: Number of steps to move.
Returns: True if the function succeeds. False if the function fails.

void PRC_Stop()

Stops the rotary. The function is called when FlexScan3D detaches the module.

Returns: nothing

BOOL PRC_GetMaxSpeed(const char* ID, int motor, double& speed)

Get the maximum speed of the rotary.

Parameters: ID: Unique ID string.; motors: Index to motor/axis.; speed: Maximum rotary speed. Speed should be between 0 and 1.0.
Returns: True if the function succeeds. False if the function fails.

BOOL PRC_SetMaxSpeed(const char* ID, int motor, double speed)

Set the maximum speed of the rotary.

Parameters: ID: Unique ID string.; motors: Index to motor/axis.; speed: Maximum rotary speed. Speed should be between 0 and 1.0.
Returns: True if the function succeeds. False if the function fails.

Optional Functions

These functions are already implemented, but you can override them if required.

BOOL PRC_Rotate(const char* ID, int motor, double degrees)

Moves the motor forward by a fixed number of degrees.

Parameters: ID: Unique ID string.; motors: Pointer to return the number of motors.; degrees: Number of degrees to rotate. Degrees should be between -360.0 and 360.0.
Returns: True if the function succeeds. False if the function fails.

BOOL PRC_GetCurrAngle(const char* ID, int motor, double& angle)

Returns the current position as an angle.

Parameters: ID: Unique ID string.; motors: Pointer to return the number of motors.; degrees: Current position as an angle. Angle returned is between -360.0 and 360.0.
Returns: True if the function succeeds. False if the function fails.

BOOL PRC_Reset(const char* ID)

Returns to the 0 position.

Returns: True if the function succeeds. False if the function fails.

C/C++ Specifics

The compiled PluginRotaryCore.dll should be put in the SDK\PluginRotary\PluginRotaryWrapper folder. The C/C++ API only supports one custom rotary plugin per FlexScan3D installation.

C# Specifics

The compiled DLL should be put in the "Rotary Modules" folder in the FlexScan3D installation folder. Multiple plugin DLLs for different motion controllers can be placed in the directory. FlexScan3D will call the BuildRotaryList in each DLL to determine which one is applicable.

The C# implementation inherits the PluginRotary interface under the PluginRotaryInterface namespace. The project should be setup to include the PluginRotaryInterface.dll from the FlexScan3D directory.

The following is the definition of the PluginRotary interface:

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using System.Configuration; namespace PluginRotaryInterface

{

public abstract class PluginRotary

{

//////////////////////////////////////////////////////////////////////////

// Default pluginID is the class name itself.

//////////////////////////////////////////////////////////////////////////

public virtual string pluginID { get { return GetType().Name; } }

/////////////////////////////////////////////////////////////////////////////////////////////

// MANDATORY: Abstract functions are used by FlexScan3D and must implemented.

/////////////////////////////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////////

// Builds the list of all the available rotaries. This function is first

// called when FlexScan3D loads the rotary module.

// The implementation should communicate with the actual rotary to determine

// if the rotary is connected.

// Parameters:

// None

// Returns:

// List of rotary IDs

// Format: "pluginID::rotaryID"

// example:

// "MyPluginClass::Rotary1"

// "MyPluginClass::Rotary2"

//////////////////////////////////////////////////////////////////////////

public abstract List<string> rotaryIDs { get; }

//////////////////////////////////////////////////////////////////////////

// Determines if a rotary is connected.

// Possible to try to reconnect or connect here.

// Parameters:

// ID - Unique rotary ID string returned by rotaryIDs

// Returns:

// True if rotary is connected. False if rotary is not connected.

//////////////////////////////////////////////////////////////////////////

public abstract bool IsConnected(string ID);

//////////////////////////////////////////////////////////////////////////

// Gets the number of motors/axis

// Parameters:

// ID - Unique ID string

// motors - Returns the number of motors.

// Returns:

// True if the function succeeds. False if function fails.

//////////////////////////////////////////////////////////////////////////

public abstract bool GetNumMotors(string ID, out int motors);

//////////////////////////////////////////////////////////////////////////

// Gets the current step position.

// Parameters:

// ID - Unique ID string

// motors - Index to motor/axis

// step - Return the current step position.

// The value is between [-StepsPerTurn, StepsPerTurn]

// Returns:

// True if the function succeeds. False if the function fails.

//////////////////////////////////////////////////////////////////////////

public abstract bool GetCurrStep(string ID, int motor, out int step);

//////////////////////////////////////////////////////////////////////////

// Gets or sets the number of step per one revolution (360 degree).

// Return 0 for displacement motors.

// Parameters:

// ID - Unique ID string

// motors - Index to motor/axis

// step - Get or Set the number of steps per turn

// Returns:

// True if the function succeeds. False if the function fails.

//////////////////////////////////////////////////////////////////////////

public abstract bool GetStepsPerTurn(string ID, int motor, out int steps);

public abstract bool SetStepsPerTurn(string ID, int motor, int steps);

/////////////////////////////////////////////////////////////////////////////////////////////

// generic motor steps interface

/////////////////////////////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////////

// Move the motor forward by fixed number of steps.

// Parameters:

// ID - Unique ID string

// motor - Index to motor/axis

// step - Number of steps to move per revolution

// Returns:

// True if the function succeeds. False if the function fails.

//////////////////////////////////////////////////////////////////////////

public abstract bool Move(string ID, int motor, int steps);

//////////////////////////////////////////////////////////////////////////

// Stops the rotary.

// Emergency brake

//////////////////////////////////////////////////////////////////////////

public abstract void Stop();

/////////////////////////////////////////////////////////////////////////////////////////////

// OPTIONAL: override if necessary

/////////////////////////////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////////

// status functions

// By default FlexScan3D doesn't use these, but you can call them from scripting

// to change rotary behavior.

// // Gets or sets the maximum speed of the rotary.

// Parameters:

// ID - Unique ID string

// motor - Index to motor/axis

// speed - Get or set max rotary speed.

// Speed should be between 0 and 1.0.

// Returns:

// True if the function succeeds. False if the function fails.

//////////////////////////////////////////////////////////////////////////

public virtual bool GetMaxSpeed(string ID, int motor, out double speed) { speed = 0; return false; }

public virtual bool SetMaxSpeed(string ID, int motor, double speed) { return false; }

//////////////////////////////////////////////////////////////////////////

// exposing advanced plugin settings to Flexscan (optional)

// public override ApplicationSettingsBase settings { get { return Properties.Settings.Default; } }

//////////////////////////////////////////////////////////////////////////

public virtual ApplicationSettingsBase settings { get { return null; } }

//////////////////////////////////////////////////////////////////////////

// Moves the motor forward by fixed number of degrees.

// Same as Move() but in degrees.

// Parameters:

// ID - Unique ID string

// motor - Index to motor/axis

// degrees - Number of degrees to turn.

// Degrees should be between -360.0 to 360.0

// Returns:

// True if the function succeeds. False if the function fails.

//////////////////////////////////////////////////////////////////////////

public virtual bool Rotate(string ID, int motor, double degrees)

{

int stepsTurn;

if (!GetStepsPerTurn(ID, motor, out stepsTurn)) return false;

if (stepsTurn <= 0) return false; // displacement motor or not set

int steps = (int)((degrees / 360.0) * stepsTurn);

return Move(ID, motor, steps);

}

//////////////////////////////////////////////////////////////////////////

// Returns the current position as an angle.

// Parameters:

// ID - Unique ID string

// motor - Index to motor/axis

// angle - Current position in degrees.

// Angle returned is between -360.0 to 360.0

// Returns:

// True if the function succeeds. False if the function fails.

//////////////////////////////////////////////////////////////////////////

public virtual bool GetCurrAngle(string ID, int motor, out double angle)

{

angle = 0;

int step;

if (!GetCurrStep(ID, motor, out step)) return false;

int stepsTurn;

if (!GetStepsPerTurn(ID, motor, out stepsTurn)) return false;

if (stepsTurn == 0) return false; // displacement

angle = step * 360.0 / stepsTurn;

//tmp[i] = 360.0f; // assume step is already clamped

return true;

}

//////////////////////////////////////////////////////////////////////////

// Returns to the 0 position.

// Parameters:

// ID - Unique ID string

// Returns:

// True if the function succeeds. False if the function fails.

//////////////////////////////////////////////////////////////////////////

public virtual bool Reset(string ID)

{

int nMotors;

if (!GetNumMotors(ID, out nMotors)) return false;

for (int i = 1; i <= nMotors; ++i)

{

int step;

if (!GetCurrStep(ID, i, out step)) return false;

//int stepsTurn = StepsPerTurn(ID, i);

//if (stepsTurn > 0) step = stepsTurn;

if (!Move(ID, i, -step)) return false;

}

return true;

}

//////////////////////////////////////////////////////////////////////////

}