Difference between revisions of "SimpleMotion V2 API documentation"

From Granite Devices Knowledge Wiki
Jump to: navigation, search
[checked revision][checked revision]
(Created page with "This page lists files and the API calls of SimpleMotion V2 C-library. ==Files== ;simplemotion.h :The header file that declares API functions and constants used in SMV2 pro...")
 
 
(24 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
This page lists files and the API calls of [[SimpleMotion V2]] C-library.
+
{{WIP}}This page lists files and the API calls of [[SimpleMotion V2]] C-library.
 
==Files==
 
==Files==
 
;simplemotion.h
 
;simplemotion.h
Line 7: Line 7:
 
;simplemotion.lib or smv.lib
 
;simplemotion.lib or smv.lib
 
:A library file needed by some Microsoft C/C++ development tools to allow usage of DLL file. Most of other tools don't need these.
 
:A library file needed by some Microsoft C/C++ development tools to allow usage of DLL file. Most of other tools don't need these.
 +
==Types==
 +
SMV2 library uses custom integer types in order to have explicitly defined bit lengths. All types translate to standard C-types.
 +
<syntaxhighlight lang="c">
 +
typedef long smbus;
 +
typedef unsigned long smuint32;
 +
typedef unsigned short smuint16;
 +
typedef unsigned char smuint8;
 +
typedef long smint32;
 +
typedef short smint16;
 +
typedef char smint8;
 +
typedef char smbool;
 +
#define smtrue 1
 +
#define smfalse 0
 +
typedef int SM_STATUS;
 +
typedef smuint8 smaddr;
 +
typedef enum _smVerbosityLevel {Off,Low,Mid,High,Trace} smVerbosityLevel;
 +
</syntaxhighlight>
  
−
==Functions==
+
SM_STATUS is returned by most of function calls and indicate the success or failure of the call. Multiple states are possible simultaneously, i.e. function may return integer value 40 which is a sum of 32 and 8 meaning both SM_ERR_COMMUNICATION and SM_ERR_LENGTH are active. Possible return values of SM_STATUS:
 +
;SM_NONE (integer value 0)
 +
:Never returned
 +
;SM_OK (integer value 1)
 +
:Call completed successfully
 +
;SM_ERR_NODEVICE (integer value 2)
 +
:Invalid ''smbus'' handle given or port not open
 +
;SM_ERR_BUS (integer value 4)
 +
:RS485 communication device error
 +
;SM_ERR_COMMUNICATION (integer value 8)
 +
:Invalid reply or no reply received from target device. Typical reasons: inexisting nodeAddress given or signal quality problem (see [[EMI]] and [[Device connection troubleshooting]])
 +
;SM_ERR_PARAMETER (integer value 16)
 +
:Illegal parameter value given
 +
;SM_ERR_LENGTH (integer value 32)
 +
:Command queue length exceeded maximum size or received return data length differs from expected length. Typical reasons: invalid/exceeded usage of queued commands or same as SM_ERR_COMMUNICATION reasons.
  
−
[[category:SimpleMotion]]
+
==Function reference==
 +
===General===
 +
{{APIdoc|smuint32|smGetVersion|()|Return SM lib version number in hexadecimal format.
 +
Ie V 2.5.1 would be 0x020501 and 1.2.33 0x010233|
 +
;return value
 +
:SMV2 library version
 +
}}
 +
 
 +
{{APIdoc|smbus|smOpenBus|( const char * devicename )|Open SM RS485 communication bus.|
 +
;devicename:
 +
:"USB2VSD" or com port as "COMx" where x=1-n, i.e. "COM15". In UNIX systems this is device path such as "/dev/ttyUSB0".
 +
;return value
 +
:handle to be used with all other commands, -1 if fails
 +
}}
 +
 
 +
Usage:
 +
<syntaxhighlight lang="c">
 +
smbus bushandle;
 +
bushandle=smOpenBus("COM5");
 +
if(bushandle<0)
 +
{
 +
  //error occurred
 +
}
 +
</syntaxhighlight>
 +
 
 +
{{APIdoc|SM_STATUS|smCloseBus|( const smbus bushandle )|Close connection to given bus handle number. This frees communication link therefore makes it available for other apps for opening.|
 +
;return value
 +
:a SM_STATUS value, i.e. SM_OK if command succeed. The SM_STATUS return value from all other functions have similar meaning.
 +
}}
 +
Usage:
 +
<syntaxhighlight lang="c">
 +
smCloseBus(bushandle);
 +
</syntaxhighlight>
 +
 
 +
{{APIdoc|void|smSetDebugOutput|( smVerbosityLevel level, FILE *stream )|Set stream where debug output is written. By default nothing is written.}}
 +
;level
 +
:set verbosity level of debugging output. Enum choices are Off,Low,Mid,High and Trace.
 +
;stream
 +
:A pointer to output stream such as stderr, stdout or a file handle.
 +
 
 +
{{APIdoc|SM_STATUS|getCumulativeStatus|( const smbus handle )|Returns all occurred SM_STATUS bits after smOpenBus or resetCumulativeStatus call|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
}}
 +
For example, this returns SM_OK if all past function calls completed without errors (does not report errors that target device may have, just SM communication related errors). I.e. will return SM_OK|SM_ERR_LENGTH (=decimal value 33) in case of some command returned SM_OK and another SM_ERR_LENGTH.
 +
 
 +
This function is provided to ease error checking by eliminating the need to inspect return value of each individual function call separately. Instead, programmer may occasionally call this function to check if any errors have occurred during longer period of time.
 +
 
 +
{{APIdoc|void|resetCumulativeStatus|( const smbus handle )|Reset cumulative status so getCumultiveStatus returns 0 after calling this until one of the other functions are called|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
}}
 +
 
 +
===Simple communication===
 +
Simple read & write of parameters commands. Single function call will perform all necessary communication with the target device, however this method is not as fast as the low level communication method (see chapter below).  Use these for non-time critical operations, such as initialization and point-to-point motion control where hard real-time control is not needed.
 +
 
 +
{{APIdoc|SM_STATUS|smRead1Parameter|( const smbus handle, const smaddr nodeAddress, const smint16 paramId1, smint32 *paramVal1 )|Read one parameter value from the target device|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
;nodeAddress
 +
:Integer value holding target device address in the bus. If unknown, connect to device with [[Granity]] to check it's address.
 +
;paramId1
 +
:Integer value specifying the parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
 +
;paramVal1
 +
:Integer pointer where read parameter is stored
 +
;Return value
 +
:{{SM_STATUS}}
 +
}}
 +
 
 +
{{APIdoc|SM_STATUS|smRead2Parameters|( const smbus handle, const smaddr nodeAddress, const smint16 paramId1, smint32 *paramVal1,const smint16 paramId2, smint32 *paramVal2 )|Read two parameter value from the target device with a single function call, this executes faster than two calls of smRead1Parameter|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
;nodeAddress
 +
:Integer value holding target device address in the bus. If unknown, connect to device with [[Granity]] to check it's address.
 +
;paramId1
 +
:Integer value specifying the first parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
 +
;paramVal1
 +
:Integer pointer where the first read parameter is stored
 +
;paramId2
 +
:Integer value specifying the second parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
 +
;paramVal2
 +
:Integer pointer where the second read parameter is stored
 +
;Return value
 +
:{{SM_STATUS}}
 +
}}
 +
 
 +
{{APIdoc|SM_STATUS|smRead3Parameters|( const smbus handle, const smaddr nodeAddress, const smint16 paramId1, smint32 *paramVal1,const smint16 paramId2, smint32 *paramVal2 ,const smint16 paramId3, smint32 *paramVal3 )|Read three parameter value from the target device with a single function call, this executes faster than equivalent operation by using smRead1Parameter or smRead2Parameter|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
;nodeAddress
 +
:Integer value holding target device address in the bus. If unknown, connect to device with [[Granity]] to check it's address.
 +
;paramId1
 +
:Integer value specifying the first parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
 +
;paramVal1
 +
:Integer pointer where the first read parameter is stored
 +
;paramId2
 +
:Integer value specifying the second parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
 +
;paramVal2
 +
:Integer pointer where the second read parameter is stored
 +
;paramId3
 +
:Integer value specifying the third parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
 +
;paramVal3
 +
:Integer pointer where the third read parameter is stored
 +
;Return value
 +
:{{SM_STATUS}}
 +
}}
 +
 
 +
{{APIdoc|SM_STATUS|smSetParameter|( const smbus handle, const smaddr nodeAddress, const smint16 paramId, smint32 paramVal )|Write single parameter value to the target device|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
;nodeAddress
 +
:Integer value holding target device address in the bus. If unknown, connect to device with [[Granity]] to check it's address.
 +
;paramId
 +
:Integer value specifying the parameter address to be written. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
 +
;paramVal
 +
:Integer value that will be written into parameter specified by paramId
 +
;Return value
 +
:{{SM_STATUS}}
 +
}}
 +
 
 +
===Low level communication===
 +
Use low level communication commands for high performance communication, such as real-time update of setpoint and feedback readouts from a real-time [[controller]]. For initialization and non-real-time communication needs, use Simple communication API (chapter above).
 +
 
 +
Low level communication involves assembing an outbound transmission packet from subpackets (with Append calls), sending it out and getting respose fromn the target device (with Excecute call) and reading out the return packet subpackets (with Get calls).
 +
 
 +
{{APIdoc|SM_STATUS|smAppendSMCommandToQueue|( smbus handle, int smpCmdType, smint32 paramvalue  )|Appends SM subpacket command to a command queue|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
;smpCmdType
 +
:Integer value holding a subpacket type. {{SMPCMD}}
 +
;paramvalue
 +
:Integer value that will be written into parameter specified by paramId
 +
;Return value
 +
:{{SM_STATUS}}
 +
}}
 +
 
 +
{{APIdoc|SM_STATUS|smExecuteCommandQueue|( const smbus bushandle, const smaddr targetaddress )|Sends all subpacket commands to the target device, and reads the response packet from target|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
;nodeAddress
 +
:Integer value holding target device address in the bus. If unknown, connect to device with [[Granity]] to check it's address.
 +
;Return value
 +
:{{SM_STATUS}}
 +
}}
 +
 
 +
{{APIdoc|STATUS |smGetQueuedSMCommandReturnValue|(  const smbus bushandle, smint32 *retValue )|Fetches an return value from returned subpacket after the call of smExecuteCommandQueue|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
;retValue
 +
:Pointer to a integer value where value if returning subpacket will be stored. {{SMPRET}}
 +
;Return value
 +
:{{SM_STATUS}}
 +
}}
 +
 
 +
===Buffered low level communucation===
 +
Buffered subpackets are executed by the target device in background at timer based schedule. This allows uploading a set of commands to drives that are excecuted at predefined execution rate. Typical application for this is motion control where trajectory points are uploaded to multiple devices and drives will follow the trajectory as commended by the buffered subpackets. Execution clock of all devices in the bus can be synchronized to ensure simultaneous execution of commands over infinite periods of time (eliminate clock drifting).
 +
 
 +
{{APIdoc|SM_STATUS|smUploadCommandQueueToDeviceBuffer|( const smbus bushandle, const smaddr targetaddress )|Uploads subpackets to the target device buffer. Subpackets are are added to local buffer with smAppendSMCommandToQueue prior to calling this function. This function also downloads returning subpackets that are already executed in the device and updates the value given by smBytesReceived. Returned subpackets may be extracted by smGetQueuedSMCommandReturnValue function.|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
;nodeAddress
 +
:Integer value holding target device address in the bus. If unknown, connect to device with [[Granity]] to check it's address.
 +
;Return value
 +
:{{SM_STATUS}}
 +
}}
 +
 
 +
{{APIdoc|SM_STATUS|smBytesReceived|( const smbus bushandle, smint32 *bytesinbuffer )|Gives the amount of how many bytes waiting to be read with smGetQueuedSMCommandReturnValue|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
;bytesinbuffer
 +
:Pointer to a integer value where value of number of bytes will be stored
 +
;Return value
 +
:{{SM_STATUS}}
 +
}}
 +
 
 +
{{APIdoc|SM_STATUS|smGetBufferClock|( const smbus handle, const smaddr targetaddr, smuint16 *clock )|Read buffered execution clock value from a device and synchronize clocks of all other bus devices to this clock value. When used, call this at least once per every three seconds to avoid side-effects from value rollover. The first call of this function begins the execution of buffered commands (on single device, or multiple devices simultaneusly).|
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
;clock
 +
:Pointer to a 16 bit integer value where the clock time will be stored. Clock counter runs at 10 kHz meaning that 16 bit value will rollover every 6.5 seconds.
 +
;Return value
 +
:{{SM_STATUS}}
 +
}}
 +
 
 +
{{APIdoc|SM_STATUS|smFastUpdateCycle|( smbus handle, smuint8 nodeAddress, smuint16 write1, smuint16 write2, smuint16 *read1, smuint16 *read2)|smFastUpdateCycle-function uses special SimpleMotion command to perform fast turaround communication. May be used with cyclic real time control. Written & read data content may be application & mode specific. This function may be called alone and it completes whole write & read cycle. '''This function is under development, do not use before this notice removed.''' |
 +
;handle
 +
:SimpleMotion bus handle as returned from smOpenBus
 +
;nodeAddress
 +
:Integer value holding target device address in the bus. If unknown, connect to device with [[Granity]] to check it's address.
 +
:Pointer to a 16 bit integer value where the clock time will be stored.
 +
;Return value
 +
:{{SM_STATUS}}
 +
}}
 +
==See also==
 +
*[[List of SimpleMotion parameters]]
 +
*[[SimpleMotion motion control strategies]] - examples etc
 +
 
 +
[[Category:SimpleMotion]]

Latest revision as of 14:55, 9 December 2016

This article is work in progress. Do not rely any of it's content until this notice is removed. You are welcome contribute by editing this page.
This page lists files and the API calls of SimpleMotion V2 C-library.

Files[edit | edit source]

simplemotion.h
The header file that declares API functions and constants used in SMV2 programs. Include this file in the C-file where SMV2 is used.
simplemotion.dll or smv.dll
A Win32 dynamic library. Place this file in application .exe folder if program is linked against the DLL. If project is being compiled with GNU GCC, then all library .c files may be added in the project to compile library statically in the program thus eliminate the need of .dll.
simplemotion.lib or smv.lib
A library file needed by some Microsoft C/C++ development tools to allow usage of DLL file. Most of other tools don't need these.

Types[edit | edit source]

SMV2 library uses custom integer types in order to have explicitly defined bit lengths. All types translate to standard C-types. 

typedef long smbus;
typedef unsigned long smuint32;
typedef unsigned short smuint16;
typedef unsigned char smuint8;
typedef long smint32;
typedef short smint16;
typedef char smint8;
typedef char smbool;
#define smtrue 1
#define smfalse 0
typedef int SM_STATUS;
typedef smuint8 smaddr;
typedef enum _smVerbosityLevel {Off,Low,Mid,High,Trace} smVerbosityLevel;

SM_STATUS is returned by most of function calls and indicate the success or failure of the call. Multiple states are possible simultaneously, i.e. function may return integer value 40 which is a sum of 32 and 8 meaning both SM_ERR_COMMUNICATION and SM_ERR_LENGTH are active. Possible return values of SM_STATUS:

SM_NONE (integer value 0)
Never returned
SM_OK (integer value 1)
Call completed successfully
SM_ERR_NODEVICE (integer value 2)
Invalid smbus handle given or port not open
SM_ERR_BUS (integer value 4)
RS485 communication device error
SM_ERR_COMMUNICATION (integer value 8)
Invalid reply or no reply received from target device. Typical reasons: inexisting nodeAddress given or signal quality problem (see EMI and Device connection troubleshooting)
SM_ERR_PARAMETER (integer value 16)
Illegal parameter value given
SM_ERR_LENGTH (integer value 32)
Command queue length exceeded maximum size or received return data length differs from expected length. Typical reasons: invalid/exceeded usage of queued commands or same as SM_ERR_COMMUNICATION reasons.

Function reference[edit | edit source]

General[edit | edit source]

smuint32 smGetVersion()

smGetVersion[edit source]

Return SM lib version number in hexadecimal format. Ie V 2.5.1 would be 0x020501 and 1.2.33 0x010233
return value
SMV2 library version
smbus smOpenBus( const char * devicename )

smOpenBus[edit source]

Open SM RS485 communication bus.

Usage: 

smbus bushandle;
bushandle=smOpenBus("COM5");
if(bushandle<0)
{
  //error occurred
}
SM_STATUS smCloseBus( const smbus bushandle )

smCloseBus[edit source]

Close connection to given bus handle number. This frees communication link therefore makes it available for other apps for opening.
return value
a SM_STATUS value, i.e. SM_OK if command succeed. The SM_STATUS return value from all other functions have similar meaning.

Usage: 

smCloseBus(bushandle);
void smSetDebugOutput( smVerbosityLevel level, FILE *stream )

smSetDebugOutput[edit source]

Set stream where debug output is written. By default nothing is written.
level
set verbosity level of debugging output. Enum choices are Off,Low,Mid,High and Trace.
stream
A pointer to output stream such as stderr, stdout or a file handle.
SM_STATUS getCumulativeStatus( const smbus handle )

getCumulativeStatus[edit source]

Returns all occurred SM_STATUS bits after smOpenBus or resetCumulativeStatus call
handle
SimpleMotion bus handle as returned from smOpenBus

For example, this returns SM_OK if all past function calls completed without errors (does not report errors that target device may have, just SM communication related errors). I.e. will return SM_OK|SM_ERR_LENGTH (=decimal value 33) in case of some command returned SM_OK and another SM_ERR_LENGTH.

This function is provided to ease error checking by eliminating the need to inspect return value of each individual function call separately. Instead, programmer may occasionally call this function to check if any errors have occurred during longer period of time.

void resetCumulativeStatus( const smbus handle )

resetCumulativeStatus[edit source]

Reset cumulative status so getCumultiveStatus returns 0 after calling this until one of the other functions are called
handle
SimpleMotion bus handle as returned from smOpenBus

Simple communication[edit | edit source]

Simple read & write of parameters commands. Single function call will perform all necessary communication with the target device, however this method is not as fast as the low level communication method (see chapter below). Use these for non-time critical operations, such as initialization and point-to-point motion control where hard real-time control is not needed.

SM_STATUS smRead1Parameter( const smbus handle, const smaddr nodeAddress, const smint16 paramId1, smint32 *paramVal1 )

smRead1Parameter[edit source]

Read one parameter value from the target device
handle
SimpleMotion bus handle as returned from smOpenBus
nodeAddress
Integer value holding target device address in the bus. If unknown, connect to device with Granity to check it's address.
paramId1
Integer value specifying the parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
paramVal1
Integer pointer where read parameter is stored
Return value
SM_STATUS holds a status value of a function call (Note: local error reporting only, such as bus error. This does not report errors that may have occurred in the target devices). See list of possible values in the beginning of this page.
SM_STATUS smRead2Parameters( const smbus handle, const smaddr nodeAddress, const smint16 paramId1, smint32 *paramVal1,const smint16 paramId2, smint32 *paramVal2 )

smRead2Parameters[edit source]

Read two parameter value from the target device with a single function call, this executes faster than two calls of smRead1Parameter
handle
SimpleMotion bus handle as returned from smOpenBus
nodeAddress
Integer value holding target device address in the bus. If unknown, connect to device with Granity to check it's address.
paramId1
Integer value specifying the first parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
paramVal1
Integer pointer where the first read parameter is stored
paramId2
Integer value specifying the second parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
paramVal2
Integer pointer where the second read parameter is stored
Return value
SM_STATUS holds a status value of a function call (Note: local error reporting only, such as bus error. This does not report errors that may have occurred in the target devices). See list of possible values in the beginning of this page.
SM_STATUS smRead3Parameters( const smbus handle, const smaddr nodeAddress, const smint16 paramId1, smint32 *paramVal1,const smint16 paramId2, smint32 *paramVal2 ,const smint16 paramId3, smint32 *paramVal3 )

smRead3Parameters[edit source]

Read three parameter value from the target device with a single function call, this executes faster than equivalent operation by using smRead1Parameter or smRead2Parameter
handle
SimpleMotion bus handle as returned from smOpenBus
nodeAddress
Integer value holding target device address in the bus. If unknown, connect to device with Granity to check it's address.
paramId1
Integer value specifying the first parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
paramVal1
Integer pointer where the first read parameter is stored
paramId2
Integer value specifying the second parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
paramVal2
Integer pointer where the second read parameter is stored
paramId3
Integer value specifying the third parameter address to be read. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
paramVal3
Integer pointer where the third read parameter is stored
Return value
SM_STATUS holds a status value of a function call (Note: local error reporting only, such as bus error. This does not report errors that may have occurred in the target devices). See list of possible values in the beginning of this page.
SM_STATUS smSetParameter( const smbus handle, const smaddr nodeAddress, const smint16 paramId, smint32 paramVal )

smSetParameter[edit source]

Write single parameter value to the target device
handle
SimpleMotion bus handle as returned from smOpenBus
nodeAddress
Integer value holding target device address in the bus. If unknown, connect to device with Granity to check it's address.
paramId
Integer value specifying the parameter address to be written. See list of SMP_xxx definitions from simplemotion_defs.h header file for possible parameters.
paramVal
Integer value that will be written into parameter specified by paramId
Return value
SM_STATUS holds a status value of a function call (Note: local error reporting only, such as bus error. This does not report errors that may have occurred in the target devices). See list of possible values in the beginning of this page.

Low level communication[edit | edit source]

Use low level communication commands for high performance communication, such as real-time update of setpoint and feedback readouts from a real-time controller. For initialization and non-real-time communication needs, use Simple communication API (chapter above).

Low level communication involves assembing an outbound transmission packet from subpackets (with Append calls), sending it out and getting respose fromn the target device (with Excecute call) and reading out the return packet subpackets (with Get calls).

SM_STATUS smAppendSMCommandToQueue( smbus handle, int smpCmdType, smint32 paramvalue )

smAppendSMCommandToQueue[edit source]

Appends SM subpacket command to a command queue
handle
SimpleMotion bus handle as returned from smOpenBus
smpCmdType
Integer value holding a subpacket type. See SimpleMotion V2 subpacket types.
paramvalue
Integer value that will be written into parameter specified by paramId
Return value
SM_STATUS holds a status value of a function call (Note: local error reporting only, such as bus error. This does not report errors that may have occurred in the target devices). See list of possible values in the beginning of this page.
SM_STATUS smExecuteCommandQueue( const smbus bushandle, const smaddr targetaddress )

smExecuteCommandQueue[edit source]

Sends all subpacket commands to the target device, and reads the response packet from target
handle
SimpleMotion bus handle as returned from smOpenBus
nodeAddress
Integer value holding target device address in the bus. If unknown, connect to device with Granity to check it's address.
Return value
SM_STATUS holds a status value of a function call (Note: local error reporting only, such as bus error. This does not report errors that may have occurred in the target devices). See list of possible values in the beginning of this page.
STATUS smGetQueuedSMCommandReturnValue( const smbus bushandle, smint32 *retValue )

smGetQueuedSMCommandReturnValue[edit source]

Fetches an return value from returned subpacket after the call of smExecuteCommandQueue
handle
SimpleMotion bus handle as returned from smOpenBus
retValue
Pointer to a integer value where value if returning subpacket will be stored. See SimpleMotion V2 subpacket types.
Return value
SM_STATUS holds a status value of a function call (Note: local error reporting only, such as bus error. This does not report errors that may have occurred in the target devices). See list of possible values in the beginning of this page.

Buffered low level communucation[edit | edit source]

Buffered subpackets are executed by the target device in background at timer based schedule. This allows uploading a set of commands to drives that are excecuted at predefined execution rate. Typical application for this is motion control where trajectory points are uploaded to multiple devices and drives will follow the trajectory as commended by the buffered subpackets. Execution clock of all devices in the bus can be synchronized to ensure simultaneous execution of commands over infinite periods of time (eliminate clock drifting).

SM_STATUS smUploadCommandQueueToDeviceBuffer( const smbus bushandle, const smaddr targetaddress )

smUploadCommandQueueToDeviceBuffer[edit source]

Uploads subpackets to the target device buffer. Subpackets are are added to local buffer with smAppendSMCommandToQueue prior to calling this function. This function also downloads returning subpackets that are already executed in the device and updates the value given by smBytesReceived. Returned subpackets may be extracted by smGetQueuedSMCommandReturnValue function.
handle
SimpleMotion bus handle as returned from smOpenBus
nodeAddress
Integer value holding target device address in the bus. If unknown, connect to device with Granity to check it's address.
Return value
SM_STATUS holds a status value of a function call (Note: local error reporting only, such as bus error. This does not report errors that may have occurred in the target devices). See list of possible values in the beginning of this page.
SM_STATUS smBytesReceived( const smbus bushandle, smint32 *bytesinbuffer )

smBytesReceived[edit source]

Gives the amount of how many bytes waiting to be read with smGetQueuedSMCommandReturnValue
handle
SimpleMotion bus handle as returned from smOpenBus
bytesinbuffer
Pointer to a integer value where value of number of bytes will be stored
Return value
SM_STATUS holds a status value of a function call (Note: local error reporting only, such as bus error. This does not report errors that may have occurred in the target devices). See list of possible values in the beginning of this page.
SM_STATUS smGetBufferClock( const smbus handle, const smaddr targetaddr, smuint16 *clock )

smGetBufferClock[edit source]

Read buffered execution clock value from a device and synchronize clocks of all other bus devices to this clock value. When used, call this at least once per every three seconds to avoid side-effects from value rollover. The first call of this function begins the execution of buffered commands (on single device, or multiple devices simultaneusly).
handle
SimpleMotion bus handle as returned from smOpenBus
clock
Pointer to a 16 bit integer value where the clock time will be stored. Clock counter runs at 10 kHz meaning that 16 bit value will rollover every 6.5 seconds.
Return value
SM_STATUS holds a status value of a function call (Note: local error reporting only, such as bus error. This does not report errors that may have occurred in the target devices). See list of possible values in the beginning of this page.
SM_STATUS smFastUpdateCycle( smbus handle, smuint8 nodeAddress, smuint16 write1, smuint16 write2, smuint16 *read1, smuint16 *read2)

smFastUpdateCycle[edit source]

smFastUpdateCycle-function uses special SimpleMotion command to perform fast turaround communication. May be used with cyclic real time control. Written & read data content may be application & mode specific. This function may be called alone and it completes whole write & read cycle. This function is under development, do not use before this notice removed.
handle
SimpleMotion bus handle as returned from smOpenBus
nodeAddress
Integer value holding target device address in the bus. If unknown, connect to device with Granity to check it's address.
Pointer to a 16 bit integer value where the clock time will be stored.
Return value
SM_STATUS holds a status value of a function call (Note: local error reporting only, such as bus error. This does not report errors that may have occurred in the target devices). See list of possible values in the beginning of this page.

See also[edit | edit source]

Retrieved from "https://granitedevices.com/w/index.php?title=SimpleMotion_V2_API_documentation&oldid=5691"