Community

	Forum
	Roboteq TV
	Follow Us
	FAQ

Controller finder

Main Menu

Home

Linux & Windows Controllers API

Tuesday, 24 August 2010 11:26

1. Introduction

The Roboteq â Devices API is a set of functions used to control motor controller behavior.

These API's come in form of static libraries that can be used on both Windows and Linux.

2. Deliverables

2.1 Windows

· RoborunDevice.lib: a static library contains the API's, which should be statically linked with your program.

· RoboteqDevice.h: contains the API's prototype.

· ErrorCodes.h: contains constants representing the error codes that can be returned by the API's.

· Constants.h: contains a set of constants representing the commands supported by the device.

· sample.cpp: a sample program representing how to use the API.

2.2 Linux

· RoborunDevice.o: object file contains the API's, which should be compiled with your program.

· RoboteqDevice.h: contains the API's prototype.

· ErrorCodes.h: contains constants representing the error codes that can be returned by the API's.

· Constants.h: contains a set of constants representing the commands supported by the device.

· sample.cpp: a sample program representing how to use the API.

3. How to use

The following is a sample to show how to use the API in a simple program:

#include <iostream>
#include <stdio.h>
#include <string.h>
#include "RoboteqDevice.h"
#include "ErrorCodes.h"
#include "Constants.h"
using namespace std;
int main(int argc, char *argv[])
{
  string response = "";
  //Create an instance of RoboteqDevice.
  RoboteqDevice device;
  //Connect to the device, for windows use    "\\\\.\\com1" for com1.
  int status = device.Connect("/dev/ttyS0");
  //Check to see if the connection succeeded.
  if(status != RQ_SUCCESS)
  {
    cout<<"Error connecting to device: "<<status<<"."<<endl;
    return 1;
  }
  cout<<"- SetConfig(_DINA, 1, 1)...";
  if((status = device.SetConfig(_DINA, 1, 1)) != RQ_SUCCESS)
    cout<<"failed --> "<<status<<endl;
  else
    cout<<"succeeded."<<endl;
  //Wait 10 ms before sending another command to device
  sleepms(10);
  int result;
  cout<<"- GetConfig(_DINA, 1)...";
  if((status = device.GetConfig(_DINA, 1, result)) != RQ_SUCCESS)
    cout<<"failed --> "<<status<<endl;
  else
    cout<<"returned --> "<<result<<endl;
  //Wait 10 ms before sending another command to device
  sleepms(10);
  cout<<"- GetValue(_ANAIN, 1)...";
  if((status = device.GetValue(_ANAIN, 1, result)) != RQ_SUCCESS)
    cout<<"failed --> "<<status<<endl;
  else
    cout<<"returned --> "<<result<<endl;
  //Wait 10 ms before sending another command to device
  sleepms(10);
  cout<<"- SetCommand(_GO, 1, 1)...";
  if((status = device.SetCommand(_GO, 1, 1)) != RQ_SUCCESS)
    cout<<"failed --> "<<status<<endl;
  else
    cout<<"succeeded."<<endl;
  device.Disconnect();
  return 0;
}

4. API Documentation

4.1 sleepms Function

Suspends the execution of the program until the timeout interval elapses.

Syntax:

void sleepms(int milliseconds)

Parameters:

milliseconds [in]

The time interval for which execution is to be suspended, in milliseconds.

Return Value:

This function does not return a value.

Remarks:

Use this function to obtain pauses between two successive device requests.

Examples:

The following example shows how to use the sleepms function to obtain pauses. The example counts down for 10 seconds.

#include <iostream>
#include <stdio.h>
#include <string.h>
#include "RoboteqDevice.h"
using namespace std;
int main(int argc, char *argv[])
{
  for(int i = 0; i < 10; i++)
  {
    cout<<"Wait for: "<<10 - i<<" second(s)."<<endl;
    sleepms(1000);
  }
  return 0;
}

4.2 RoboteqDevice:: Connect

Opens a connection to the device connected to a specified port.

Syntax:

int Connect(string port)

Parameters:

port [in]

The port that device is attached to.

Return Value:

One of the following values determines the operation status:

Value	Constant	Description
0	RQ_SUCCESS	The operation completed successfully.
1	RQ_ERR_OPEN_PORT	Error occurred while trying to open the communication port.
7	RQ_UNRECOGNIZED_DEVICE	The device is not recognized.
8	RQ_UNRECOGNIZED_VERSION	Invalid device version.

Examples:

The following example shows how to obtain a connection to Roboteq device.

#include <iostream>
#include <stdio.h>
#include <string.h>
#include "RoboteqDevice.h"
#include "ErrorCodes.h"
#include "Constants.h"
using namespace std;
int main(int argc, char *argv[])
{
  //Create an instance of RoboteqDevice.
  RoboteqDevice device;
  //Connect to the device, for windows use "\\\\.\\com1" for com1.
  int status = device.Connect("/dev/ttyS0");
  //Check to see if the connection succeeded.
  if(status != RQ_SUCCESS)
  {
    cout<<"Error connecting to device: "<<status<<"."<<endl;
    return 1;
  }
  cout<<"Connection to device succeeded."<<endl;
  device.Disconnect();
  return 0;
}

4.3 RoboteqDevice:: Disconnect

Closes the connection to the device.

Syntax:

void Disconnect()

Parameters:

This function does not need any parameters.

Return Value:

This function does not return a value.

Examples:

See RoboteqDevice:: Connect example.

4.4 RoboteqDevice:: IsConnected

Checks whether connection to device is opened.

Syntax:

bool IsConnected()

Parameters:

This function does not need any parameters.

Return Value:

Returns true if the device connection is open, false otherwise.

4.5 RoboteqDevice:: SetConfig

Changes one of the controller's configuration parameters. The changes are made in the controller's RAM and take effect immediately. Configuration changes are not stored in EEPROM.

Syntax:

int SetConfig(int configItem, int index, int value)
int SetConfig(int configItem, int value)

Parameters:

configItem [in]

The configuration item needs to be changed. See Table 1 below for constants that can be used with this function.

index [in]

Used to select one of the configuration item in multi-channel configurations. When accessing a configuration parameter that is not part of an array, the index value 1 must be used. Details on the various configurations items, their effects and acceptable values can be found in the Controller's User Manual.

If the index is omitted, it is supposed to be 0.

value [in]

The new parameter configuration value.

Table 1 Configuration Items Constants

*Config Item*	*Description*	*Config Item*	*Description*
_ACS	Enable Ana Center Safety	_EMOD	Encoder Operating Mode
_ACTR	Analog Center	_EPPR	Encoder PPR
_ADB	Analog Deadband	_ICAP	Motor(s) Int Cap
_AINA	Analog Input Actions	_KD	Set PID Differential Gain
_ALIM	Motor Amps Limit	_KDC1	KD Curve Points for Motor1
_ALIN	Analog Linearity	_KDC2	KD Curve Points for Motor2
_AMAX	Analog Max	_KI	Set PID Integral Gain
_AMAXA	Action on Analog Input Max	_KIC1	KI Curve Points for Motor1
_AMIN	Analog Min	_KIC2	KI Curve Points for Motor2
_AMINA	Action on Analog Input Min	_KP	Set PID Proportional Gain
_AMOD	Analog Input Mode	_KPC1	KP Curve Points for Motor1
_AMS	Enable Ana Min/Max Safety	_KPC2	KP Curve Points for Motor2
_APOL	Analog Input Polarity	_MAC	Motor(s) Desired Acceleration
_ATGA	Amps Trigger Action	_MDEC	Motor(s) Desired Deceleration
_ATGD	Amps Trigger Delay	_MMOD	Motor Operating Mode
_ATRIG	Amps Trigger Value	_MVEL	Motor(s) Default Position Velocity
_BHL	Encoder High Limit	_MXPF	Motor Max Power
_BHLA	Encoder High Limit Action	_MXPR	Motor Max Power
_BHOME	Brushless Counter Load at Home Position	_MXRPM	Motor RPM at 100%
_BLFB	Speed and Position sensor feedback	_MXTRN	Number of Motor Turns between Limits
_BLL	Encoder Low Limit	_PCTR	Pulse Center
_BLLA	Encoder Low Limit Action	_PDB	Pulse Deadband
_BLSTD	BL Stall Detection	_PIDM	Set PID Options
_BPOL	Number of Poles of BL Motor	_PINA	Pulse Input Actions
_CLERD	Close Loop Error Detection	_PLIN	Pulse Linearity
_CLIN	Command Linearity	_PMAX	Pulse Max
_DFC	Default Command value	_PMAXA	Action on Pulse Input Max
_DINA	Digital Input Action	_PMIN	Pulse Min
_DINL	Read Digital Inputs	_PMINA	Action on Pulse Input Min
_DOA	Digital Output Action	_PMOD	Pulse Input Mode
_DOL	Digital Output Action	_PMS	Enable Pulse Min/Max safety
_ECHOF	Disable/Enabe RS232 & USB Echo	_PPOL	Pulse Input Polarity
_EHL	Encoder High Limit	_RWD	RS232 Watchdog (0 to disable)
_EHLA	Encoder High Limit Action	_SXC	Sepex Curve Points
_EHOME	Encoder Counter Load at Home Position	_SXM	Minimum Field Current
_ELL	Encoder Low Limit
_ELLA	Encoder Low Limit Action

Return Value:

One of the following values determines the operation status:

Value	Constant	Description
0	RQ_SUCCESS	The operation completed successfully.
2	RQ_ERR_NOT_CONNECTED	The device not connected, you should call the Connect function and insure that the device connection succeeded.
3	RQ_ERR_TRANSMIT_FAILED	Error occurred while transmitting data to device.
4	RQ_ERR_SERIAL_IO	Error occurred to serial communication.
5	RQ_ERR_SERIAL_RECEIVE	Error occurred while transmitting data from device.
6	RQ_INVALID_RESPONSE	Invalid response to the issued command.
9	RQ_INVALID_CONFIG_ITEM	Invalid configuration item, it should be in the range [0, 255].
12	RQ_INDEX_OUT_RANGE	The item index is out of range.
13	RQ_SET_CONFIG_FAILED	Failed to set device configuration.

Examples:

See sample.cpp.

4.6 RoboteqDevice:: GetConfig

Reads one of the controller's configuration parameters.

Syntax:

int GetConfig(int configItem, int index, int &result)
int GetConfig(int configItem, int &result)

Parameters:

configItem [in]

The configuration item needs to be read. See Table 1 above for constants that can be used with this function.

index [in]

If the index is omitted, it is supposed to be 0.

result [out]

Contains the configuration item value in case of function success.

Return Value:

One of the following values determines the operation status:

Value	Constant	Description
0	RQ_SUCCESS	The operation completed successfully.
2	RQ_ERR_NOT_CONNECTED	The device not connected, you should call the Connect function and insure that the device connection succeeded.
3	RQ_ERR_TRANSMIT_FAILED	Error occurred while transmitting data to device.
4	RQ_ERR_SERIAL_IO	Error occurred to serial communication.
5	RQ_ERR_SERIAL_RECEIVE	Error occurred while transmitting data from device.
6	RQ_INVALID_RESPONSE	Invalid response to the issued command.
9	RQ_INVALID_CONFIG_ITEM	Invalid configuration item, it should be in the range [0, 255].
12	RQ_INDEX_OUT_RANGE	The item index is out of range.
14	RQ_GET_CONFIG_FAILED	Failed to get device configuration.

Examples:

See sample.cpp.

4.7 RoboteqDevice:: SetCommand

This function is used to send operating commands to the controller at runtime. The function requires a Command Item, and a Value as parameters. The Command Item can be any one from the table below. Details on the various commands, their effects and acceptable ranges can be found in the Controller's User Manual.

Syntax:

int SetCommand(int commandItem, int index, int value)
int SetCommand(int commandItem, int value)

Parameters:

commandItem [in]

The command item needs to be set. See Table 2 below for constants that can be used with this function.

index [in]

Used to select one of the command channel in multi-channel commands. Details on the various commands, their effects and acceptable ranges can be found in the Controller's User Manual.

If the index is omitted, it is supposed to be 0.

value [in]

The new command value.

Table 2 Command Items Constants

*Command Item*	*Description*
ACCEL	Set Acceleration
_DECEL	Set Deceleration
_DOUT	Set all Digital Out bits
_DRES	Reset Individual Digital Out bits
_DSET	Set Individual Digital Out bits
_ESTOP	Emergency Shutdown
_GO	Set Motor1 Command
_HOME	Load Home counter

Return Value:

One of the following values determines the operation status:

Value	Constant	Description
0	RQ_SUCCESS	The operation completed successfully.
2	RQ_ERR_NOT_CONNECTED	The device not connected, you should call the Connect function and insure that the device connection succeeded.
3	RQ_ERR_TRANSMIT_FAILED	Error occurred while transmitting data to device.
4	RQ_ERR_SERIAL_IO	Error occurred to serial communication.
5	RQ_ERR_SERIAL_RECEIVE	Error occurred while transmitting data from device.
6	RQ_INVALID_RESPONSE	Invalid response to the issued command.
11	RQ_INVALID_COMMAND_ITEM	Invalid command item, it should be in the range [0, 255].
12	RQ_INDEX_OUT_RANGE	The item index is out of range.
16	RQ_SET_COMMAND_FAILED	Failed to set device command.

Examples:

See sample.cpp.

4.8 RoboteqDevice:: GetValue

Reads one of the controller's operating parameters.

Syntax:

int GetValue(int operatingItem, int index, int &result)
int GetValue(int operatingItem, int &result)

Parameters:

operatingItem [in]

The operating item needs to be read. See Table 3 below for constants that can be used with this function.

index [in]

Used to select one of the operating item in multi-channel configurations. When accessing operating parameter that is not part of an array, the index value 1 must be used. Details on the various operating items, can be found in the Controller's User Manual.

If the index is omitted, it is supposed to be 0.

result [out]

Contains the operating item value in case of function success.

Table 3 Operating Items Constants

*Config Item*	*Description*	*Config Item*	*Description*
_ABCNTR	Absolute Encoder Count	_FLTFLAG	Fault Flags
_ABSPEED	Encoder Motor Speed in RPM	_LOCKED	Lock status
_ANAIN	Analog Inputs	_LPERR	Closed Loop Error
_BATAMPS	Battery Amps	_MOTAMPS	Motor Amps
_BLCNTR	Absolute Brushless Counter	_MOTCMD	Actual Motor Command
_BLRCNTR	Brushless Count Relative	_MOTPWR	Applied Power Level
_BLRSPEED	BL Motor Speed as 1/1000 of Max	_PLSIN	Pulse Inputs
_BLSPEED	BL Motor Speed in RPM	_RELCNTR	Encoder Count Relative
_CMDANA	Internal Analog Command	_RELSPEED	Encoder Motor Speed as 1/1000 of Max
_CMDPLS	Internal Pulse Command	_STFLAG	Status Flags
_CMDSER	Internal Serial Command	_TEMP	Case & Internal Temperatures
_DIGIN	All Digital Inputs	_TIME	Time
_DIGOUT	Current Digital Outputs	_VAR	User Variable
_DIN	Individual Digital Inputs	_VOLTS	Internal Voltages
_FEEDBK	Feedback

Return Value:

One of the following values determines the operation status:

Value	Constant	Description
0	RQ_SUCCESS	The operation completed successfully.
2	RQ_ERR_NOT_CONNECTED	The device not connected, you should call the Connect function and insure that the device connection succeeded.
3	RQ_ERR_TRANSMIT_FAILED	Error occurred while transmitting data to device.
4	RQ_ERR_SERIAL_IO	Error occurred to serial communication.
5	RQ_ERR_SERIAL_RECEIVE	Error occurred while transmitting data from device.
6	RQ_INVALID_RESPONSE	Invalid response to the issued command.
10	RQ_INVALID_OPER_ITEM	Invalid operating item, it should be in the range [0, 255].
12	RQ_INDEX_OUT_RANGE	The item index is out of range.
15	RQ_GET_VALUE_FAILED	Failed to get operating item value.

Examples:

See sample.cpp.

Joomla SEO powered by JoomSEF

Latest News

My cart

Your Cart is currently empty.

Community

Controller finder

Main Menu

1. Introduction

2. Deliverables

2.1 Windows

2.2 Linux

3. How to use

4. API Documentation

4.1 sleepms Function

4.2 RoboteqDevice:: Connect

4.3 RoboteqDevice:: Disconnect

4.4 RoboteqDevice:: IsConnected

4.5 RoboteqDevice:: SetConfig

4.6 RoboteqDevice:: GetConfig

4.7 RoboteqDevice:: SetCommand

4.8 RoboteqDevice:: GetValue

Latest News

Popular

My cart