SimpleMotion V2 API documentation
 | 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. |
Contents
Files
- 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
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
General
smGetVersion
- return value
- SMV2 library version
smOpenBus
Usage:
smbus bushandle; bushandle=smOpenBus("COM5"); if(bushandle<0) { //error occurred }
smCloseBus
- 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);
smSetDebugOutput
- 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.
getCumulativeStatus
- 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.
resetCumulativeStatus
- 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.
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 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.
smRead2Parameters
- 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.
smRead3Parameters
- 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.
smSetParameter
- 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
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).
smAppendSMCommandToQueue
- 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.
smExecuteCommandQueue
- 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.
smGetQueuedSMCommandReturnValue
- 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
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).
smUploadCommandQueueToDeviceBuffer
- 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.
smBytesReceived
- 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.
smGetBufferClock
- 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.
In no event the Product Information or parts hereof shall be regarded as guarantee of conditions or characteristics. The Product Information or any part thereof may also not be regarded as a warranty of any kind. No liability of any kind shall be assumed by Author with respect to Product Information or any use made by you thereof, nor shall Author indemnify you against or be liable for any third party claims with respect to such information or any use thereof.
As content of this Wiki may be edited by user community, Granite Devices Oy or it's affiliates do not take any responsibility of the contents of this Wiki. Use information at your own risk. However, Granite Devices staff attempts to review all changes made to this Wiki and keep information trustworthy.
Without written consent, Granite Devices' Products or Intellectual Property shall not be used in situations or installations where living beings, material property, or immaterial property could be harmed by the operation, features or failures of Product. Products may only be used in a way where hazards like moving parts, electric shock, laser radiation, or fire can't be realized even if the content of this Wiki would suggest otherwise.
