SimpleMotion V2 API documentation

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.

Functions

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.

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.