LED Matrix (EN)

  • Configuration of the LED Matrix. Among others changing destinations, different destinations on the front and side, inverting single elements or the entire display and even free positioning of single elements.


    2 Introduction

    Hello! You’ve probably ended up here, because you want to know how to configure the LED Matrix.

    Maybe you’ve ended up here by chance and want to know what this is about?

    This article describes the configuration possibilities of an LED Matrix, which isn’t included in the Standard Content, but are available in the Steam Workshop under the following links:

    The special thing about this matrix is, that is is relatively freely configurable.

    It can, among other things, show changing destinations, different destinations on the front and side, invert elements or the entire display and even free positioning of elements (strings, etc.) - at least if you’re brave enough to play around with it ;-)

    These instructions will be expanded, as the possible functions are implemented.

    3 Crash course

    3.1 Special PIS and what happens in it

    The matrix uses special PIS data. The class is "LED_BERLIN".

    In this PIS file, you can configure almost everything. The following is, however, just a start.

    The creation of a special PIS file alone changes the function of the matrix. Even when it doesn’t contain anything, the white display uses a different boot sequence and the formatting is different in details.

    3.2 Lesson 1: Simple terminus configurations :-D

    Before we dive into the many other options, we should take a look at what probably interests most people: Simple customisation of destinations, creating changing destinations, etc.

    The information, which tells how a destination should be shown, are entered as XML data in the “Additional strings” field of the selected stop in the left pane and always have the following structure:

    3.2.1 Main element and type

    <terminus> is the main element. Without it, the whole thing wouldn’t work.

    <simple> indicates, that this is a simple destination definition. There are also complex definitions, but more about those in another place.

    3.2.2 Panel

    Inside the element <simple> is one or more <panel> elements. This configures the displays installed in the vehicle according to the order of Module Slots. The last <panel> element is used on every other displays. This allows for the front display to show something different from all the other displays.

    3.2.3 Content

    The <content> element is what the display is to show.

    Here, one or two strings are defined. These overwrites the strings from the general PIS file. They have a value (the string itself) and could also be inverted:

    1. <string1>
    2. <value>Musterhausen</value>
    3. </string1>
    4. <string2>
    5. <value>via Bahnhof</value>
    6. <inverted>true</inverted>
    7. </string2>

    Important: There is no fallback to the basic strings.

    Inverted can be “true” or “false”. The standard value is “false”.

    Other than that, an entire display area can be inverted:

    1. <inverted>full</inverted>

    Possible arguments are “line”, “terminus”, “full” and “none”. The standard value is “none”. This explains itself, or?

    It is also possible to make one of the strings smaller than the other:

    1. <smallerstring>1</smallerstring>

    The value is “1” or “2” and tells which string should be the smaller one.

    Aaaand then there’s:

    1. <time>2</time>

    If there’s more than one <content> elements, the display cycles through these. This time declares how long the current content is to be shown, before it switches to the next.

    The value is in seconds, and the standard and minimum value is 1.

    3.2.4 Examples

    1. I just want to overwrite the strings.

    2. I want to display something different in the front than on the side*.

    3. I want to have a changing destination.

    4. I want to make the first line smaller than the second.

    5. I want to invert the whole display.

    6. I want to make the second line inverted.

    4 Special PIS-class

    To configure the displays, a special PIS file of the class “LED_BERLIN” is needed.

    Additionally, some of the modules load another special PIS file, whose class name contains a postfix. This is mentioned in the module name and the description of the corresponding module.

    At the moment, this applies to for example both Berlin variants of the white matrix with the postfixes “_2014” and “_2018”. Therefore, these load both the special PIS “LED_BERLIN” and correspondingly “LED_BERLIN_2014” or “LED_BERLIN_2018”.

    The special PIS files add to each other. It is therefore possible to change single destinations or settings of displays of one or both modules without copying the whole special PIS.

    5 Additional strings of the PIS group

    The additional strings of the PIS (typed in the upper right corner, see also this) mainly configures the behavior of the display.

    They follow the INI format, except for a few deviations. There are sections, where the various keys and their values are grouped. This means, that one section corresponds to a configuration element and the keys are the parameters of this element.

    When a module loads an additional special PIS, the additional strings of this additional special PIS (for example LED_BERLIN_2014) is loaded first, and just after this, the normal special PIS (LED_BERLIN) is loaded. When both special PIS files are present, the definitions from the additional PIS overrules those from the normal special PIS.

    The value of the parameter which was loaded first always counts. In the case of sections that are applied to certain conditions, the first occurrence that matches the conditions defined there also counts.

    This allows for settings defined in the normal special PIS to overwrite an additional special PIS. The exception is the section [local], in that it contains settings only applicable to the special PIS in which it is written.

    In the following is a list of possible sections and parameters.

    (The list is not complete and is continuously updated)

    5.1 Global and local settings

    5.1.1 Global parameters

    Section [settings]

    Here, global settings are written. The settings from the normal special PIS (LED_BERLIN) can be overwritten in an additional special PIS (e.g LED_BERLIN_2014).

    The section can be defined multiple times, however only the first loaded value counts.

    special_chars This deactivates the special characters from the general PIS.

    true - The special characters from the general PIS are used (default value if the parameter isn’t declared).
    false - No special characters are used.
    count_is_id This setting determines how the displays in the vehicle are numbered. More on this where it is important (will follow later ;))

    true - The modules are numbered independently from their properties. This means, that the internal numbering corresponds to the address shown during display boot.
    false - The internal numbering takes the size of the display into account (default value when not defined).
    auto_format When there’s no complex configuration to a destination, it will be formatted after set rules. This function is activated with this parameter. The default value of this is false.

    The rules which the automatic formatting is to follow, must be defined separately in the sections [auto_format:regex] and [auto_format:rule]. There are no standard rules. This parameter will only work, if the rules are defined as well.

    5.1.2 Local parameters

    Section [local]

    The settings in this section exclusively effect the current PIS. This means, that whatever is defined in the LED_BERLIN is only valid for LED_BERLIN and vice versa with LED_BERLIN_2014/2018.

    complex_fallback BIn the case of complex destination configurations, specific displays are defined. If a display is not defined, these could then be empty or fall back to those from the general PIS. The behavior is determined through this parameter.

    true - The display falls back to the basic strings.
    false - The display remains empty (Default value).
    complex_auto_format This parameter is only relevant, if complex_fallback is set to true.
    t defines if the automatic formatting should be used by a fallback to the basic strings, if the global parameter “auto_format” is activated.

    true - The automatic formatting is applied (auto_format must be true as well).
    false - It is not applied (default value).

    5.1.3 Example

    1. [settings]
    2. count_is_id = true
    3. auto_format = true
    4. special_chars = false
    5. [local]
    6. complex_fallback = true
    7. complex_auto_format = false

    5.2 Rules of the formatting of basic PIS strings

    5.2.1 Replacement of strings/regular expressions

    Section [auto_format:regex]

    Any number of regular expressions and substitutions can be specified, which are applied to the strings of the basic PIS. For each regular expression, one of these sections must be specified with both parameters. The parameters are:

    pattern The regular expression.
    replace The replacement.

    5.2.2 Advanced formatting

    Section [auto_format:rule]

    This section is more complex. For every rule, a section must be created. This time, the order is important, since there are conditions which rely on other rules.

    string1_pattern, string2_pattern A regular expression to compare the string with.
    string1_replace, string2_replace A substitution which fits to a regular expression. With this, the string is either changed or replaced. This happens before every other instructions in the rule is applied.
    if_no_prev_match The rule is applied, if no other rules were applied.
    break After this rule, no other rules are applied.
    cat_strings true - string1 and string2 are joined into one (cat = short form of concatenate).
    false - Default value. The strings aren't joined.
    cat_if_enough_space The parameter expects "cat_strings = true".
    true - "cat_strings" is only performed if the display is wide enough for the string.
    false - cat_strings" is always performed (default value).
    cat_with_space The parameter expects "cat_strings = true".
    true - A space is added between the strings when joining.
    false - The strings are joined without a space (default value).
    smallerstring This parameter makes one of the strings smaller than the other.
    1 - The first string is made smaller.
    2 - The second string is made smaller.
    The default value is 0.

    to be continued ...

    5.2.3 Example

    5.3 Modification of line numbers

    Section [linemod]

    These can occur multiple times. Here, line number modifications are applied. You could also call it special characters without special character code ;-)

    5.3.1 Parameters

    When are the modifications used?

    The following two parameters determine the combination of lines and special characters for which the modifications defined in this section are to be applied. Both conditions must be met.

    line_pattern A regular expression with which the line number is compared.
    specialchar_pattern A regular expression with which the special character code is compared.

    Replacement of line and terminus

    The line as well as the terminus can be overwritten.

    line_replace A substitution that matches the regular expression 'line_pattern'. This generates the resulting line string.
    override_terminus This is used to overwrite the terminus. The specified value is interpreted as the ID of an additionally configured terminus (see section [terminus]).


    As standard, the lines are formatted according to rules specified in a line modification. They’re centered in the line field with the largest possible font and spacing. This format can be overwritten:

    no_format true - Disables automatic formatting. It is assumed that it is a non-modified line number. These are shown left adjusted with a standard font and a spacing of 1.
    false - The formatting is applied (default).

    Due to the size difference of the displays, it is possible to define for each display, how the automatic formatting should be overwritten. The displays are defined using abbreviations, which are contained in the parameters:

    32f 32px high, line and terminus
    26f 26px high, line and terminus
    26l 26px high, only line
    19f 19px high, line and terminus
    19l 19px high, only line

    The parameters are therefore:

    format_X_align Replace X with the display abbreviation (e.g. format_32f_align), see above.

    With this, the automatic alignment can be overwritten. The values are “left”, “center” or “right”. The default overwrite value is “center”.
    format_X_offset Replace X with the display abbreviation (e.g. format_32f_offset), see above.

    With this, an offset can be set. This is in comparison to the standard formatting, which already contains and offset of 1. If a left adjusted line should also touch the left edge of the display, the offset should be “-1”.
    format_X_spacing Replace X with the display abbreviation (e.g. format_32f_spacing), see above.

    This parameter overwrites the spacing.

    Formatting under additional conditions

    It is possible to create a second formatting, which is only active when certain conditions regarding the line-specialchar-combination are met:

    cond_line A regular expression with which the line number is compared.
    cond_specialchar A regular expression with which the specialchar code is compared.
    See the corresponding “format_X...”-parameter.

    5.3.2 Examples

    Here are some examples with detailed explanation to further clarify the possibilities:

    Example 1: Customization of line numbers from 401 to 412:

    More examples to come

    5.4 Definition of destinations not contained in the basic PIS

    Section [terminus]

    coming soon...

    5.5 Creating destination templates

    Section [terminustemplate]

    coming soon...

    6 Simple terminus configurations

    coming soon...

    7 Complex terminus configurations

    This kind of configuration is interesting, when it comes to freely arranging texts and symbols on the display. The font and position of the text can be specified very precisely. Other than that, it is possible to add a few other elements, such as rectangles and checkboard patterns.

    These possibilities obviously requires more advanced additional strings in the special PIS. Have fun ;-)

    7.1 Structure of a complex terminus configuration

    The additional strings must contain another XML of the following structure:

    Does it look like the simple? Yes. There is only one difference: The second element is complex instead of simple.

    The blocks panel and the inside content are described in the following.

    7.2 Panel

    A panel here equals a complete display. These are differentiated based on their size (number of pixels), their position (sequence of the module slots) and their content (line, target or both). Accordingly, different destinations can be defined for these different panels.

    7.2.1 Attributes

    The specification for which type of display a panel element is to be used is done via the attributes of this element:

    Attribute Description
    size Size in the format width x height, e.g. size = "200x32" The white matrix currently has "200x32", "192x26", "144x26" and "48x26". In the future there will also be "240x32". The amber colored ones are available as "140x19", "128x19", "112x19" and "28x19". required
    count Position in the module order. The value depends on the global parameter "count_is_id".
    For example, if a vehicle has a front display of size 200x32 and a display of size 192x26 on the side and in the rear, only one of the two 192x26 displays can be addressed via this attribute. Which one it is depends on the "count_is_id" parameter:
    count="2" with count_is_id = true is the side display because all displays are counted (the counter corresponds to the ID, therefore the parameter is called so. Front has ID 1, side has ID 2).
    count="2" with count_is_id = false s the rear display, because only the displays of the same size are counted: side is 1, rear is 2.
    content This allows you to further narrow down which display the element relates to. The values "line", "terminus" and "both" are possible.
    content="terminus" means that the element only applies to displays that only display the destination.

    7.2.2 Assignment and order

    Actually, the first element that matches the attributes is used for a display. Unfortunately, there is still a bug, which is why elements with stronger restrictions should currently be higher up in the XML. A <panel size="192x26" content="terminus"> should come before a <panel size="192x26">.

    Important: Displays, for whose no matching element exists, show no destination! There is no fallback to the basic PIS.

    7.2.3 Sub elements

    Inside the panel elements are the content elements. Additionally there are also two interesting elements:

    Element Description Amount
    <defaults>false/true</defaults> A boolean that can be used to define that these displays should only show the standard strings from the basic PIS. Since displays for which there is no element remain off, an "empty" element can be created here. An empty panel element without this setting is not sufficient to access the standard strings. Only once
    <noautoformat>false/true</noautoformat> With this, if <defaults>true</defaults> is specified, the automatic formatting of standard strings can be deactivated if this is activated globally. Only once
    The content block is described in the next section.
    With <defaults>true</defaults> these are ignored.
    beliebig oft

    7.3 Content

    A content element contains everything that is to be seen on the display. More elements result in the display cycling through these. The time till the next elements shows can be defined.

    7.3.1 Attributes

    There are two attributes which makes life easier for us, when there are more content elements which only differs slightly:

    Attribute Description
    id This can be used to give the element an ID so that it can be copied later. For example, id="blub". optional
    cp If a content element with an ID exists further up, it can be copied completely to the current position with this attribute.
    cp="blub" would copy the element defined above with the attribute id="blub".

    In copied content elements, it is possible to make minor adjustments to the subordinate elements (see "id", "ref", "del" of the sub elements).

    7.3.2 Sub elements

    Inside a content element there are the elements that draw certain texts, symbols or other things on the display. There are also a few settings for the entire content element:

    Element Description Amount
    <time>X</time> If there is more than one content element, this defines how long the display shows this element before switching to the next. It is displayed in seconds and there are limits that I can’t remember in my head. Only once
    <inverted>none/line/terminus/full</inverted> This setting defines whether the line number or the destination or the entire display should be inverted. Only once
    Writes a string. See below. As many as you want
    Draws a “barrier tape”. See below. As many as you like
    Draws a rectangle with borders or filled. See below. As many as you like
    Draws a rectangle with a checkboard pattern. See below. As many as you like

    7.4 Writing text/symbols (string)

    With the <string> element, you can write whatever you wish to the display. You can freely define the font, spacing and position.

    This means that various symbols can also be drawn anywhere on the display. A list of the available fonts with the symbols they contain follows.

    7.4.1 Sub elements

    Element Description
    <value>String</value> The string to be written.
    <font>FontID-String</font> The name of the font. There is a list of which can be used, but it is yet to be completed.

    Important: This has nothing to do with content IDs or the like. The fonts are defined internally. It is not yet possible to add your own fonts.
    <spacing>N</spacing> The spacing, aka the distance between the characters. Default is 1.
    <unlockspacing>false/true</unlockspacing> If the position is not specified absolute, but relative within a defined area (see position and area), this parameter can be set to true to allow the blocking to be reduced if there is not enough space in the area.
    <inverted>false/true</inverted> With this, the string can be inverted.
    See positioning of content elements (position, area).
    See positioning of content elements (position, area).

    7.5 Drawing a barrier tape (tape)

    Barrier tape means a diagonally striped tape. This can be drawn at any position in different heights and lengths.

    7.5.1 Sub elements

    Still not finished. To come...

    7.6 Drawing a rectangle (box)

    With or without borders. Bla bla

    7.6.1 Sub elements

    Element Description
    Identical to <area>, see Positioning of content elements (position, area).

    The element defines the area of the rectangle. If <outer> is not defined, this corresponds to the rectangle. If <outer> is also specified, this is the area around which the frame is drawn.
    Identical to <area>, see Positioning of content elements (position, area).

    his optional element corresponds to a range. This area is the area of the rectangle, whereby the area defined by <inner> is cut out. The result is a frame.

    7.7 Drawing a checkboard pattern (checkerboard)

    In a rectangular area.

    7.7.1 Sub elements

    Element Desscription
    The area in which the checkboard pattern is drawn. See positioning of content elements (position, area).
    <inverted>false/true</inverted> It may sound weird, but the checkboard pattern can be inverted as well. It controls if the pattern starts with white or black in the upper left corner.

    7.8 Attributes of the content element

    All elements that are used to represent things on the display (string, tape, box, checkerboard) have the following attributes with which these elements can be copied, edited or deleted. More details in the table:

    Attribute Description
    id This attribute gives the element an ID so that it can be identified later. For example <string id="meinString">.
    cp With this attribute, an element that exists further up in the XML and has an ID can be copied to the current position. For example <string cp="meinString">. Sub elements then overwrite the data copied from the original. You can, for example, use <string cp="meinString"><value>Hello</value></string> o copy the string with the ID "myString" and thus use the defined font, spacing and position, but overwrite the text with " Hello".
    ref When a content element is copied, all sub elements also exist in the new content element. In order to be able to adapt one of these, this attribute must be used instead of "cp". For example <string ref="meinString">. Otherwise everything is identical to "cp".
    del The same as with “ref”, but the element from the copied content are deleted.

    7.9 Positioning of content elements (position, area)

    The content elements (string, tape, box, checkerboard) can be positioned anywhere on the display. In the case of a string, this works both absolutely and relatively within a defined range. The remaining elements are positioned by specifying an area.

    7.9.1 Defining an area with area (inner, outer)

    The specification of an area is optional for a string and mandatory for a rectangle and checkerboard pattern. The rectangle has this element twice under the names "inner" and "outer", but its content and functionality are identical.

    In the case of a string, the definition of an area is interesting when it comes to relative positioning or when the string is inverted.

    When inverting, the entire specified area is inverted. If no area is defined, one is automatically set for this.

    However, if no area is defined with relative positioning, this will not happen and the result will most likely not be what you want it to be.

    Within the area element (or inner/outer) an area is defined using the coordinates of the upper left corner (x1, y1) and the lower right corner (x2, y2).

    Element Description
    Specifies the coordinates on the display. The upper left corner of the display corresponds to the coordinates x = 0, y = 0.

    7.9.2 Defining the position with position

    The strings and barrier tape are positioned using this position information:

    Element Description
    Indication of coordinates on the display. The upper left corner of the display corresponds to the coordinates x = 0, y = 0.
    <halign>left/center/right</halign> Only available for a string. Horizontal alignment within the defined area. If no area is defined, something happens, but probably not what you want.
    <valign>top/middle/bottom</valign> Only available for a string. Vertical alignment within the defined area. If no area is defined, something happens, but probably not what you want.

    8 Using templates

    To come...

    9 Miscellaneous

    Got any questions? Got any comments? Please write them in this forum thread ;-)