Difference between revisions of "SimpleMotion V2 API documentation"

From Granite Devices Knowledge Wiki
Jump to: navigation, search
[checked revision][checked revision]
(Functions)
(Functions)
Line 41: Line 41:
 
: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.
 
: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.
  
==Functions==
+
==Function reference==
 +
===General===
 
{{APIdoc|smuint32|smGetVersion|()|Return SM lib version number in hexadecimal format.
 
{{APIdoc|smuint32|smGetVersion|()|Return SM lib version number in hexadecimal format.
 
Ie V 2.5.1 would be 0x020501 and 1.2.33 0x010233}}
 
Ie V 2.5.1 would be 0x020501 and 1.2.33 0x010233}}
Line 73: Line 74:
 
;stream
 
;stream
 
:A pointer to output stream such as stderr, stdout or a file handle.
 
: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}}
 +
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}}
 +
 +
===Communication===
 +
 +
{{APIdoc|SM_STATUS|smAppendSMCommandToQueue|( smbus handle, int smpCmdType, smint32 paramvalue  )|Appends SM command to a command queue}}
 +
{{APIdoc|SM_STATUS|smExecuteCommandQueue|( const smbus bushandle, const smaddr targetaddress )|Executes all commands (communication to target device happens in this call) that are previously appended to the SM queue}}
 +
 +
{{APIdoc|STATUS |smGetQueuedSMCommandReturnValue|(  const smbus bushandle, smint32 *retValue )|Fetches an return value of SM command that has been executed during the last smExecuteCommandQueue call}}
 +
 +
{{APIdoc|SM_STATUS|smUploadCommandQueueToDeviceBuffer|( const smbus bushandle, const smaddr targetaddress )|}}
 +
{{APIdoc|SM_STATUS|smBytesReceived|( const smbus bushandle, smint32 *bytesinbuffer )|}}
 +
 +
 +
{{APIdoc|SM_STATUS|smAppendGetParamCommandToQueue|( smbus handle, smint16 paramAddress )|}}
 +
{{APIdoc|SM_STATUS|smGetQueuedGetParamReturnValue|(  const smbus bushandle, smint32 *retValue  )|}}
 +
{{APIdoc|SM_STATUS|smAppendSetParamCommandToQueue|( smbus handle, smint16 paramAddress, smint32 paramValue )|}}
 +
{{APIdoc|SM_STATUS|smGetQueuedSetParamReturnValue|(  const smbus bushandle, smint32 *retValue  )|}}
 +
 +
/** Simple read & write of parameters with internal queueing, so only one call needed.
 +
Use these for non-time critical operations. */
 +
{{APIdoc|SM_STATUS|smRead1Parameter|( const smbus handle, const smaddr nodeAddress, const smint16 paramId1, smint32 *paramVal1 )|}}
 +
{{APIdoc|SM_STATUS|smRead2Parameters|( const smbus handle, const smaddr nodeAddress, const smint16 paramId1, smint32 *paramVal1,const smint16 paramId2, smint32 *paramVal2 )|}}
 +
{{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 )|}}
 +
{{APIdoc|SM_STATUS|smSetParameter|( const smbus handle, const smaddr nodeAddress, const smint16 paramId, smint32 paramVal )|}}
 +
{{APIdoc|SM_STATUS|smGetBufferClock|( const smbus handle, const smaddr targetaddr, smuint16 *clock )|}}
 +
  
 
[[Category:SimpleMotion]]
 
[[Category:SimpleMotion]]

Revision as of 10:59, 9 August 2015

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 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

smuint32 smGetVersion()

smGetVersion

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

smOpenBus

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:

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

smCloseBus

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

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

Returns all occurred SM_STATUS bits after smOpenBus or resetCumulativeStatus call

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

Reset cumulative status so getCumultiveStatus returns 0 after calling this until one of the other functions are called

Communication

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

smAppendSMCommandToQueue

Appends SM command to a command queue
SM_STATUS smExecuteCommandQueue( const smbus bushandle, const smaddr targetaddress )

smExecuteCommandQueue

Executes all commands (communication to target device happens in this call) that are previously appended to the SM queue
STATUS smGetQueuedSMCommandReturnValue( const smbus bushandle, smint32 *retValue )

smGetQueuedSMCommandReturnValue

Fetches an return value of SM command that has been executed during the last smExecuteCommandQueue call
SM_STATUS smUploadCommandQueueToDeviceBuffer( const smbus bushandle, const smaddr targetaddress )

smUploadCommandQueueToDeviceBuffer

SM_STATUS smBytesReceived( const smbus bushandle, smint32 *bytesinbuffer )

smBytesReceived


SM_STATUS smAppendGetParamCommandToQueue( smbus handle, smint16 paramAddress )

smAppendGetParamCommandToQueue

SM_STATUS smGetQueuedGetParamReturnValue( const smbus bushandle, smint32 *retValue )

smGetQueuedGetParamReturnValue

SM_STATUS smAppendSetParamCommandToQueue( smbus handle, smint16 paramAddress, smint32 paramValue )

smAppendSetParamCommandToQueue

SM_STATUS smGetQueuedSetParamReturnValue( const smbus bushandle, smint32 *retValue )

smGetQueuedSetParamReturnValue

/** Simple read & write of parameters with internal queueing, so only one call needed. Use these for non-time critical operations. */

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

smRead1Parameter

SM_STATUS smRead2Parameters( const smbus handle, const smaddr nodeAddress, const smint16 paramId1, smint32 *paramVal1,const smint16 paramId2, smint32 *paramVal2 )

smRead2Parameters

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

SM_STATUS smSetParameter( const smbus handle, const smaddr nodeAddress, const smint16 paramId, smint32 paramVal )

smSetParameter

SM_STATUS smGetBufferClock( const smbus handle, const smaddr targetaddr, smuint16 *clock )

smGetBufferClock