SynqNet Drive Parameters

Introduction

SynqNet drives may have drive-specific parameters. These parameters are used to provide drive-specific information to the user or allow the user to change the drive configuration.

Examples of read-only drive parameters are: amplifier power rating, amplifier temperature, motor capacity, motor serial number, encoder type, etc.

Examples of read/write drive parameters are: maximum torque limit, maximum speed limit, gravity compensation, etc.

Drive parameters are implemented for particular drive models and firmware versions. The MPI library contains a general drive parameter interface—able to handle any set of drive parameters— independent of the MPI library version. It uses a drive parameter map file to determine the valid drive parameters. Individual drive parameters can be set (or read) using MPI methods or the sqDriveParam utility program. A list of drive parameters can be set (or read) using MPI methods or the sqDriveConfig utility program.

Drive Parameter methods:
mpiSqNodeDriveParamGet/ Set
mpiSqNodeDriveParamListGet/ Set
mpiSqNodeDriveMapParamFileGet/ Set

This document defines the drive parameter map file format and instructions for SynqNet partners to generate/update map files for their customers and SynqNet controller software distributions.

Drive Parameter Map File

The drive parameter map file contains a list of valid drive parameters for a particular drive model. The filename format is:

Where “Manufacturer” is the name of the company that makes the drive and “Model” is the product name for the drive series.

The drive parameter map file is a text file containing the drive parameter map whose format is as follows:

#”Manufacturer Model” “drive firmware version”
The name of the manufacturer, the model number, and the drive firmware versions that are compatible with the drive parameter list.

#parameters
Designates the beginning of the valid drive parameter map for the versions listed above.

number, name, read/write, data type, values, default value, and help string
Each line in the #parameters section contains the map for each drive parameter.

number – drive parameter number (in hex).

name – drive parameter name.

read/write – read/write or read-only (rw or ro).

data type – one of the pre-defined data types (see table below).

values – list of valid values, range of valid values, or an address.

default value – parameter value to be used if value is not specified.

help string – simple string to provide user help.

#config
Designates the beginning of the configuration section.

name
List of parameter names that can be downloaded to a drive from a drive configuration file or uploaded from a drive to a configuration file using the sqDriveConfig utility.

//
Indicates a comment and the line is ignored by the parser.

#end
Designates the end of the parameter map file.

For example, here is a generic drive parameter map file for drive firmware versions 1.0 and 1.1:


#”Manufacturer Model” “1.0” “1.1”
#parameters
0x01 Param_1  rw signed16   {1~100}         0 "help string for Param 1"
0x02 Param_2  ro signed16   {10~1100}       0 "help string for Param 2"
0x03 Param_3  rw signed32   {100~10000000}  0 "help string for Param 3"
0x04 Param_4  rw signed16   {2,4,6,8,10}    0 "help string for Param 4"
// 0x5 not available
0x06 Param_6  rw signed32   {*}             0 "help string for Param 6"

#config
Param_1
Param_3
Param_4
Param_6
#end

and here is a parameter map file example for drive firmware versions (1.0 and 1.1) and 1.2:


#”Manufacturer Model” “1.0” “1.1”
#parameters
0x01 Param_1  rw signed16   {1~100}         0 "help string for Param 1"
0x02 Param_2  ro signed16   {10~1100}       0 "help string for Param 2"
0x03 Param_3  rw signed32   {100~10000000}  0 "help string for Param 3"
0x04 Param_4  rw signed16   {2,4,6,8,10}    0 "help string for Param 4"
// 0x5 not available
0x06 Param_6  rw signed32   {*}             0 "help string for Param 6"

#config
Param_1
Param_3
Param_4
Param_6
#end

#”Manufacturer Model” “1.2”
#parameters
0x01 Param_1 rw signed16 {1~100} 0 "help string for Param 1"
0x02 Param_2 ro signed16 {10~1100} 0 "help string for Param 2"
0x03 Param_3 rw signed32 {100~10000000} 0 "help string for Param 3"
0x04 Param_4 rw signed16 {2,4,6,8,10} 0 "help string for Param 4"
// 0x5 not available
0x06 Param_6 rw signed32 {*} 0 "help string for Param 6"
0x07 Param_7 rw unsigned16 {*} 0 "help string for Param 7"
0x08 Param_8 rw enumerated {0=neg,1=pos} 0 "help string for Param 8"

#config
Param_1
Param_3
Param_4
Param_6
Param_7
Param_8
#end

All service commands and drive parameters are accessed over the service channel as 32-bit quantities, but these 32 bits of data can represent many different types of data. To support various data types with generic software tools, the supported data types have been predefined. Here are the data type names that are supported for the drive parameter map file.

Name	Description
unsigned8	An 8-bit unsigned binary number.
unsigned16	A 16-bit unsigned binary number.
unsigned32	A 32-bit unsigned binary number.
signed8	An 8-bit binary, twos-complement number.
signed16	A 16-bit binary, twos-complement number.
signed32	A 32-bit binary, twos-complement number.
hex	A 32-bit unsigned hexadecimal number (same as unsigned32 but displayed as hexadecimal).
enumerated	A list of numbers 1, 2, 3, 4 where each number has a specific meaning (same as unsigned32 but displayed as a selectable list).
mask	A set of bits 1, 2, 4, 8 where each bit has a specific meaning (same as unsigned32 but displayed as a set of selectable flags).
character	An ASCII character.
string	An ASCII string. Max length is 256.
single	A 32-bit floating pint number according to IEEE754.
action	A write-only parameter where the data is always zero. It performs an action/command on the drive that does not need any data.

For write commands that are less than 32 bits, the drive processor can ignore the extra data. For read commands that are less than 32 bits the drive processor should pad the data with sign extension bits for signed quantities or pad with zeros for unsigned quantities.

SynqNet drive parameters are identified by number. This makes it possible to support a uniform interface for drive parameters. If your drive requires memory addresses for drive parameters, please contact MEI for MPI node library support BEFORE creating a drive parameter map file.

WARNING!
If new drive parameters are added, then they must be assigned numbers that have NOT been previously used. Drive parameter numbers must NOT be redefined. Following this rule will prevent users from setting drive parameter data to the wrong drive parameter in the drive. It will make existing drive map files forward compatible with new drive firmware (although new drive parameters would not be supported by the existing map files) and new drive map files backward compatible with older drive firmware (although new drive parameters would not be supported by older drive firmware).

For example, to add new parameters to an existing map:


0x01 Param_A  rw signed16   {1~100}          0 "help string for Param A"
0x02 Param_B  ro signed16   {10~1100}        0 "help string for Param B"
0x03 Param_C  rw signed32   {100~10000000}   0 "help string for Param C"
// 0x04 Param_D – previously used, no longer supported  
0x05 Param_E  rw signed32   {*}              0 "help string for Param E"

The next parameters would be 0x06, 0x07, 0x08, etc.
Do NOT redefine parameters 0x01, 0x02, 0x03, 0x04, or 0x05.

Map File Distribution

MEI will distribute the drive parameter map files with the MPI library software package. The map files are located in the xmp\bin directory. If you would like your drive parameter map file to be distributed with the MPI library, please provide the file to MEI.

SynqNet drive partners can distribute drive parameter map files to customers. MEI strongly recommends that the drive parameter map file is updated and distributed when a new drive firmware version is distributed. This will ensure that customers have access to drive parameters that are compatible with a particular drive firmware version.

Before distributing drive map files, be sure to run the map file validation utility. The dmFileValidate.exe will check the .dm file and display any errors caught by the Drive Map module, as well as errors in the valid values field.

For example, running dmFileValidate with a valid .dm file:

Using Parameter Map Files

The utility programs sqDriveParam and sqDriveConfig can be used to read/write drive parameters. Both of these programs require that the appropriate drive parameter map file (manufacturer_model.dm), be available in the path or accessible via a command line switch.

sqDriveParam.exe can be used to read/write a single drive parameter.

sqDriveConfig.exe can be used to read/write a list of drive parameters.

The MPI library has methods to access the drive map file and read/write individual drive parameters or a list of drive parameters.

For more information about Drive Map and Drive Parameter Access, please see the SqNode object and DriveMap object.