User Tools

Site Tools


userpages:hermannk:function_mapping-en

What is Function Mapping

Foreword 0: as described in the wiki, the settings are only saved if the "Description" field contains an entry!!!
see Description

Foreword 1: the function zero (function "F0") has a special role. It is intended for the "light" function and there is therefore no way to redirect function number zero to another function number (mapping).

Foreword 2: if the handheld controller enables easy-to-read function labels, mapping should avoided, but rather display the full range of functions of each locomotive individually on the handheld controller.

Foreword 3:
3a) not all locomotive and/or function controllers do support 32 function numbers;
3b) not all protocols do support 32 function numbers.
Inside this documentation function number 32 is reserved for "do nothing". If this is not possible in a given configuration please define a function number other than 32 that is reserved for "do nothing". There may also be the need of having one reserved function number for locomotive controllers and another reserved function number for function controllers.

Why Function Mapping?

Using a handheld controller to control the locomotive and the locomotive functions, there is often no space on its buttons for extensive labeling and certainly no possibility for variable labeling. Somehow we have to deal with the function numbers from 1 to 32.


The following function number assignment could exist for three locomotives:

Manufacturer Manufacturer Manufacturer
Locomotive 1 Locomotive 2 Locomotive 3
Function Function Function
# Description # Description # Description
0 light 0 light 0 light
1 head light 1 1 rear light 1 whistle
2 head light 2 2 whistle 2 smoke
3 horn 1 3 pantograph 3 brake
4 horn 2 4 distant light 4
5 distant light 5 brake 5
6 coupler loco 6 sand 6
7 fan 7 engine 7
8 brake 8 8
9 motor sound 9 9
10 sand 10 10
11 cabin light 1 11 11
12 cabin light 2 12 12
13 rear light 13 13
xx xxxx xx xxxx xx xxxx


One possibility is to define yourself one function number list that should apply to all locomotives.

In this example, the function numbers are to be used as follows:

Function Usage
F1 to F9 Locomotive functions
F10 to F19 Train / car functions
F20 to F31 available
F32 reserved


The following requirements are made in this description:

Handheld control assignment Manufacturer Manufacturer Manufacturer
for all locomotives Locomotive 1 Locomotive 2 Locomotive 3
Function Function Function Function
# Description # Description # Description # Description
0 light 0 light 0 light 0 light
1 rear light 1 head light 1 rear light 1 whistle
2 cabin light 1 2 rear light 2 whistle 2 smoke
3 whistle 3 horn 1 3 pantograph 3 brake
4 brake 4 horn 2 4 distant light 4
5 smoke 5 distant light 5 brake 5
6 engine 6 coupler loco 6 sand 6
7 pantograph 7 fan 7 engine 7
8 coupler loco 8 brake 8 8
9 shunting gear 9 motor sound 9 9
10 interior lighting 10 sand 10 10
11 coupler car 1 11 front cabin light 11 11
12 coupler car 2 12 rear cabin light 12 12
13 coupler car 3 13 rear light 13 13
14 coupler car 4 14 14 14
xx xxxx xx xxxx xx xxxx xx xxxx
32 reserved 32 reserved 32 reserved 32 reserved


With the function numbers-mapping for each locomotive, the fixed handheld function numbers can be translated into locomotive-dependent function numbers. The following cases can occur:

the handheld control function is available in the locomotive the handheld control function is not available in the locomotive
function numbers are the same function numbers are not the same no matter
pass on the function redirect function (map) redirect to unused function number
F3 "whistle" → F3 "horn 1" F4 "brake" → F8 "brake" F7 "pantograph" → F32 "reserved"

Prerequisite is however: function number 32 does not occur in our locomotive!

How to configure a function mapping?

In the properties of our locomotive, at first create the fixed handheld controller function number list (e.g. by "copying" an already well-established locomotive). Then enter the manufacturer function number of our locomotive in the fx column. The reserved function number 32 is entered for all functions that do not occur.
In this example, the range of functions of the handheld controller is defined as follows:
- handheld function numbers 1 to 9 are reserved for the locomotives;
- handheld function numbers 10 to 19 are reserved for trains / car s;
- handheld function numbers 20 to 31 can be used individually;
- the handheld controller function number 32 is reserved as "unused".

Handheld controller assignment Manufacturer
Our locomotive Our locomotive
Locomotive Function Function
Address Mapping
11 # Description Address fx # Description
0 light - - 0 light
1 rear light 0 13 1 light front
2 cabin light 0 11 2 light rear
3 whistle 0 0 3 horn 1
4 brake 0 8 4 horn 2
5 smoke 0 32 5 distant light
6 engine 0 9 6 coupler loco
7 pantograph 0 32 7 fan
8 coupler loco 0 32 8 brake
9 shunting gear 0 24 9 motor sound
10 interior lighting 0 32 10 sand
11 coupler car 1 0 32 11 front cabin light
12 coupler car 2 0 32 12 rear cabin light
13 coupler car 3 0 32 13 rear light
14 coupler car 4 0 32 14
15 - 0 32 15
16 - 0 32 16 cabin door open/close
17 - 0 32 17 Fader
18 - 0 32 18
19 - 0 32 19 compressor
20 - 0 32 20
21 - 0 32 21 curve squeak
22 - 0 32 22 parking lights
23 - 0 32 23 solo trip
24 - 0 32 24 shunting gear
25 - 0 32 25
26 - 0 32 26
27 - 0 32 27
28 - 0 32 28
29 - 0 32 29
30 - 0 32 30
31 - 0 32 31
32 reserved 0 0 32

Special feature: Rocrail processing time is saved if a zero is used in the mapping for the same function numbers for handheld and locomotive: fx = 0
Example: handheld control # = 3 "whistle" and our locomotive fx = 0 "horn 1"

Locomotive properties / functions

In this example, button 9 on the handheld controller should be the "shunting gear" for all locomotives;
- our new locomotive uses function no. 24 for the shunting gear;
- the mapping fx = 24 is then entered in the properties of our locomotive for function # = 9.


Car features / functions

As for a locomotive, a function number list for a car can also be specified …

… and if necessary it can be incorporated into the function number list of a locomotive. (see "coupler car 1" to "coupler car 4" in the table above).

Mapping at "Locomotive with train"

The functions of "Locomotive and Train" have now been defined on the handheld controller.

Handheld control assignment
Function
# Description
xx xxxx
10 interior lighting
11 coupler car 1
12 coupler car 2
13 coupler car 3
14 coupler car 4
xx xxxx
32 reserved


Basically, Rocrail passes on the function number of the handheld controller to the locomotive as well as to all cars in the train.

n each car there is then the option of redirecting the hand controller function number to a car function (mapping).

Handheld controller Car
# Description # Description Fx
F5 xxxx F5 coupler F32
F10 interior lighting F10 interior lighting 0
F11 coupler car 1 F11 F5

Example: hand controller # = 11 "Coupling car 1" is redirected to car function 5 by Fx = 5 for car 1 ("car151").

Handheld control assignment Manufacturer Manufacturer
Our locomotive Our car 1 ("car151") Our car 2 ("car152")
Locomotive Function Function Function
Address Mapping Mapping Mapping
11 # Description Address fx # Description Fx # Description Fx
xx xxxx - - xx xxxx xx xx xxxx xx
5 smoke 0 32 5 coupler 32 5 coupler 32
xx xxxx - - xx xxxx xx xx xxxx xx
10 interior lighting 0 32 10 interior lighting 0 10 interior lighting 0
11 coupler car 1 0 32 11 coupler car 1 5 11 32
12 coupler car 2 0 32 12 32 12 coupler car 2 5
13 coupler car 3 0 32 13 32 13 32
14 coupler car 4 0 32 14 32 14 32
xx xxxx 0 32 xx xx xx xx
32 reserviert; 0 0 32 0 32 0

With this configuration the functions of the locomotive can be operated, the two cars can be uncoupled individually and the interior lighting can be switched on and off in all cars at the same time.


Mapping to address and function number

There are vehicles that have a separate function decoder with a separate address installed. To support this the definition for the function mapping may use an address in addition to the function number. see https://wiki.rocrail.net/doku.php?id=loc-fun-en#address_fx
An example for a separate function decoder address of a locomotive (without a train) can be found at **Test 6**.

Practical test

The function definitions for a locomotive and two cars listed in this documentation should be checked for their validity in several tests. For this purpose, the train "op_51-en" was coupled to the locomotive "lc_11-en", which consists of the two cars "car151-en" and "car152-en". After clicking a function button on the handheld controller, the result was read out in Rocview's controller trace window and documented here.

Locomotive Train
lc_11-en op_51-en
Car 1 Car 2
car151-en car152-en


Preliminary note 1: Addresses are used for an MBUS controller:

ID Address [hex] Address [dec]
lc_11-en 0x406F 111
car151-en 0x4097 151
car152-en 0x4098 152

Preliminary note 2: "fn=32, val=1" means: function-nummer=32, value=1
Preliminary note 3: the tests were done with Rocrail version 2.1.755 with this workspace.

Test 1 - whistle

The locomotive should whistle and the two cars do nothing; the handheld controller function number is identical to the locomotive function number:

Handheld controller Locomotive Mapping Car 1 Mapping Car 2 Mapping
Brief description: F3 = "whistle" fx=0 car151 Fx=32 car152 Fx=32
Result: loco [lc_11-en] addr=0x406F fn=3, val=1
loco [car151-en] addr=0x4097 fn=32, val=1
loco [car152-en] addr=0x4098 fn=32, val=1
Passed the test.

Test 2 - Shunting

The locomotive is supposed to activate the "shunting gear" and the two cars do nothing; the hand controller function number is different with regard to the locomotive function number:

Handheld controller Locomotive Mapping Car 1 Mapping Car 2 Mapping
Brief description: F9 = "Shunting" fx=24 car151 Fx=32 car152 Fx=32
Result: loco [lc_11-en] addr=0x406F fn=24, val=1
loco [car151-en] addr=0x4097 fn=32, val=1
loco [car152-en] addr=0x4098 fn=32, val=1
Passed the test.

Test 3 - interior lighting

The locomotive doesn't do anything, but all cars should activate the "interior lighting":

Handheld controller Locomotive Mapping Car 1 Mapping Car 2 Mapping
Brief description: F10 = "interior lighting" fx=32 car151 Fx=0 car152 Fx=0
Result: loco [lc_11-en] addr=0x406F fn=32, val=1
loco [car151-en] addr=0x4097 fn=10, val=1
loco [car152-en] addr=0x4098 fn=10, val=1
Passed the test.

Test 4 - coupler car 2

The locomotive doesn't do anything, but car 2 should activate the coupler:

Handheld controller Locomotive Mapping Car 1 Mapping Car 2 Mapping
Brief description: F12 = "coupler car 2" fx=32 car151 Fx=32 car152 Fx=5
Result: loco [lc_11-en] addr=0x406F fn=32, val=1
loco [car151-en] addr=0x4097 fn=32, val=1
loco [car152-en] addr=0x4098 fn=5, val=1
Passed the test.

Test 5 - coupler car 1

The locomotive doesn't do anything, but car 1 should activate the coupler:

Handheld controller Locomotive Mapping Car 1 Mapping Car 2 Mapping
Brief description: F11 = "coupler car 1" fx=32 car151 Fx=5 car152 Fx=32
Result: loco [lc_11-en] addr=0x406F fn=32, val=1
loco [car151-en] addr=0x4097 fn=5, val=1
loco [car152-en] addr=0x4098 fn=32, val=1
Passed the test.

Test 6 - separate function address

The handheld controller does function F27
- for locomotive "lc_11plus-en" which has the address 113 = 0x4071 and
- the separate controller has the address 114 = 0x4072.
The locomotive doesn't do anything, but the separate function decoder should execute function number 26:
F27 Adresse="114"="0x4072" fx="26"

Handheld controller Locomotive Mapping to separate address
Address Function
Brief description: F27 = "special" Address=114 fx=26
Result: loco [lc_11plus-en] addr=0x4072 fn=26, val=1
Passed the test.
userpages/hermannk/function_mapping-en.txt · Last modified: 2020/06/02 14:56 by smitt48