USERSCALAR / OPTUSERSCALAR

User scalars allow the units, scalar and offset to be defined by the user within GW. By specifying the units (including table axis units and map x and y axis units) as a name in brackets (e.g. ‘(load)’) a user scalar is created with the appropriate name (if necessary) and assigned to the type.

Since GIN version 3.33, DELETE

Supported by Ginmake 2.38 and later.

1[DELETE,name[,type]]

Extend an existing item of the given name and, optionally, type in case of ambiguity.

e.g.

1[DELETE,Engine RPM]
2[DELETE,Load,table]
3[DELETE,Load,channel]

DESCRIPTION, ALIAS

Ginmake 2.62+

1[ALIAS,name,alias_name[,type]]

Clone object named ’name’ of type ’type’ with new name ‘alias_name’. Type field is optional.

Note that for more control, the following is now also possible in ginmake 2.62+, to create a new object at the same location as the EXTEND item:

// [EXTEND,TIC 01 Time][TC1,,,,r,+,i,,,]

ATTRIBUTES are supported on USERSCALAR / OPTUSERSCALAR.

The actual parameters of the user scalar are defined using the following methods for fixed value scalars and offsets and option user scalars:

1;[USERSCALAR,<name>,<units>,<FP?>,<format>,<m>,<c>]
2;[OPTUSERSCALAR,<name>,<units>,<FP?>,<format>,
3; <scalaroptname>,<sm>,<sc>,<s\*or/>, <offsetoptname>,<om>,<oc>,<o\*or/>, <chainoptname>]

If a value uses a user scalar, the scaled value is calculated using the function:

scaled = raw value * m + c

Scaled values of option user scalars are detailed below the table.

For the user scalar definition, the fields are defined as follows:

Field Name Definition
USERSCALAR This is entered as is and defines the values as a user scalar.
Name Defines the name of the user scalar as seen in the user selectable units in GW and AEMPro. Must be specified and match an existing user scalar. If the name is prefixed with ‘!’ then the user scalar will be hidden from units configuration. Supported in GIN version 3.33, GWv4.03.45.
Units Defines the default units used by values assigned with the user scalar. Defaults to an empty string. A unit quantity may also be specified by using a colon ‘:’ character with the quantity before the colon and unit afterwards. See 9 The quantity should be the ‘script name’ for the quantity. Also, the script name for the unit can be used when a quantity is specified. e.g. afr:LA for Air Fuel Ratio : λ If the unit’s field is encapsulated in O[…], this refers to an option that has an enumeration defining the units. The enumeration must only contain the names of user scalars that will become a dynamic chained user scalar.
FP? Defines whether the default scaled value uses floating-point. A ‘y’ or ‘Y’ indicates floating-point. Defaults to integer.
Format Defines the default format used by the default user scalar. Defaults to an empty string.
M Defines the default scalar. Defaults to 1.
C Defines the default offset. Defaults to 0.

For the option user scalar definition, the fields are defined as follows:

Field Name Definition
OPTUSERSCALAR This is entered as is and defines the values as an option user scalar.
Name Defines the name of the option user scalar as seen in the user selectable units in GW and AEMPro. Must be specified and match an existing user scalar. If the name is prefixed with ‘!’ then the user scalar will be hidden from units configuration. Supported in GIN version 3.33, GWv4.03.45.
Units Defines the default units used by values assigned with the user scalar. Defaults to an empty string. A unit quantity may also be specified by using a colon ‘:’ character with the quantity before the colon and unit afterwards. See 9 The quantity should be the ‘script name’ for the quantity. Also, the script name for the unit can be used when a quantity is specified. e.g. afr:LA for Air Fuel Ratio : λ If the unit’s field is encapsulated in O[…], this refers to an option that has an enumeration defining the units. The enumeration must only contain the names of user scalars that will become a dynamic chained user scalar. Dynamic units will override the chained user scalar, if defined.
FP? Defines whether the default scaled value uses floating-point. A ‘y’ or ‘Y’ indicates floating-point. An empty or other value indicates otherwise. Defaults to integer.
Format Defines the default format used by the default user scalar. Defaults to an empty string.
Scalaroptname Defines the name of the option used in the scalar. If the field is blank the scalar is not option scaled.
sm Defines the scalar multiplier. If no scalar option is defined this value is used as the scalar multiplier. Defaults to 1.
sc Defines the scalar offset. If no scalar option is defined this value is unused. Defaults to 0.
s*or/ Defines whether the scalar option is multiplied or dividing into the value of sm. If no scalar option is defined this value is unused. A ‘/’ indicates the scalar option is a divisor. Defaults to multiply.
Offsetoptname Defines the name of the option used in the offset. If the field is blank the offset is not option scaled.
om Defines the offset multiplier. If no offset option is defined this value is used as the offset multiplier. Defaults to 1.
oc Defines the offset. If no offset option is defined this value is unused. Defaults to 0.
o*or/ Defines whether the offset option is multiplied or dividing into the value of sm. If no offset option is defined this value is unused. A ‘/’ indicates the offset option is a divisor. Defaults to multiply.
Chainusname Defines the name of a chained user scalar name. If blank, no user scalar is chained to the option user scalar. If O[…] is used in the unit’s field for dynamic units, it will override the chained user scalar. It can be useful to leave this in if you might need to convert the gin file to an older version.

If a value uses an option user scalar, the scaled value is calculated using the same function as user scalars, but the values of m and c are calculated using separate functions:

scaled = * +

If a scalar option is defined the value of m is calculated using one of the functions:

if <s*or/> is set as ‘*’, m = * +

if <s*or/> is set as ‘/’, m = / +

else m is set to

The value of c is similarly calculated for its respective fields of , , and <o*or/>.

If the offset/scalar option values are zero and division is used, the values are treated as if they were 1.

AFR Units Example

Some units require calibration through an option user scalar before a meaningful unit can be assigned to it. An example of this is Air Fuel Ratio (AFR).

From GWv4 2.03.45, it is possible to use dynamic chained units in user scalars so that the chosen calibrated units can be stored in the ECU. Prior to this, base unit overrides would need to be stored outside of the ECU, making the calibration less portable.

Multiple interacting elements are required to implement this feature in an ECU definition file:

AFR units that may be selected for this ECU. These user scalars associate a name with a unit ID and are looked up from the AFR_UNIT_LIST enumeration. So that these items do not show up in user unit selection in GW, their names are prefixed ‘!’ to hide them.

1[USERSCALAR,!AFR Not Calibrated,AFR Not Calibrated,y,,,]
2[USERSCALAR,!AFR Lambda,afr:LA,y,,,]
3[USERSCALAR,!AFR Ethanol,afr:AFR Ethanol,y,,,]
4[USERSCALAR,!AFR Methanol,afr:AFR Methanol,y,,,]
5[USERSCALAR,!AFR Gasoline,afr:AFR Gasoline,y,,,]
6[USERSCALAR,!AFR Diesel,afr:AFR Diesel,y,,,]
7[USERSCALAR,!AFR Propane,afr:AFR Propane,y,,,]
8[USERSCALAR,!AFR Hydrogen,afr:AFR H2,y,,,]
9[USERSCALAR,!AFR CNG,afr:AFR CNG,y,,,]

Enumeration used for selection of chained user scalar from the AFR Base Units option. This lists the USERSCALAR items that specify the AFR units:

1[ENUM=AFR_UNIT_LIST, 0,AFR Not Calibrated, 1,AFR Lambda, 2,AFR Ethanol, 3,AFR Methanol, 4,AFR Gasoline, 5,AFR Diesel, 6,AFR Propane, 7,AFR Hydrogen, 8,AFR CNG ]

Unit scalar, will offer unit conversions if a base unit has been set via AFR Base Units option – the AFR Base Units option is specified here via O[…]:

1[USERSCALAR,AFR Units,O[AFR Base Units],y,,,]

Option User Scalar for calibration factors from raw values to an AFR unit. This is chained to the AFR Units user scalar. Option User Scalars do not offer unit overrides in GEMS GW software.

1[OPTUSERSCALAR,AFR,,y,,AFR Scalar,,,,AFR Offset,,,,AFR Units]

Calibration Option allowing user to specify the units that AFR is calibrated to:

uint8_t afr_units; // [AFR Base Units,,ol(AFR_UNIT_LIST),,o,,,,]

Calibration Options for the AFR scaling factors:

1int16_t afr_scalar; // [AFR Scalar,,\*0.001,0,o,2,f,,]
2int16_t afr_offset; // [AFR Offset,,\*0.001,0,o,2,f,,]

Example Option using the AFR scaling chain:

1uint8_t lambda_target; // [Lambda Target,(AFR),,,o,,,,]
2 // [Lambda Target Raw,,,,o,,,,]