1 HUGE THANKS TO thor2950 FOR THE TRANSLATION!
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
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:
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:
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:
The value is “1” or “2” and tells which string should be the smaller one.
Aaaand then there’s:
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.
- <terminus><simple>
- <panel>
- <content>
- <time>2</time>
- <string1><value>I'm the first part of the</value></string1>
- <string2><value>changing destination</value></string2>
- </content>
- <content>
- <time>2</time>
- <string1><value>I'm the second part of the</value></string1>
- <string2><value>changing destination</value></string2>
- </content>
- </panel>
- </simple></terminus>
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
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
- [auto_format:regex]
- pattern = "(Rath)\.?( |$)"
- replace = "\1aus\2"
- [auto_format:rule]
- string1_pattern = ^.*\/$
- cat_strings = true
- cat_if_enough_space = true
- break = true
- [auto_format:rule]
- string1_pattern = ^(S|U|S\+U|U\+S)-Bahnhof$
- string1_replace = \1
- cat_strings = true
- cat_with_space = true
- break = true
- [auto_format:rule]
- string2_pattern = ^(via|->).*$
- smallerstring = 2
- break = true
- [auto_format:rule]
- if_no_prev_match = true
- smallerstring = 1
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]). |
Formatting
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. |
cond_format_X_align cond_format_X_offset cond_format_X_spacing |
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:
The regular expression under “line_pattern” is applicable to all line numbers starting with 4 and either have a ‘0’ in the second position and any number in the third, or a ‘1’ in the second and a ‘0’, ‘1’ or ‘2’ in the third. The number must end after the third digit.
The parameter “specialchar_pattern” isn’t specified, which means that the special character doesn’t matter.
This means that these modification rules are applied to all line numbers from 401 to 412, regardless of the special character.
Next comes the “line_replace” parameter with the value “\2\3”. This is a substitution that cuts out the groups 2 and 3 from the string and writes them one after the other. The groups are defined by brackets in the regular expression:
- Both digits after the 4 (this group is necessary due to the OR link)
- The last digit if the second digit is 0
- Also both digits after the 4 if there is no 0 in the second position
The groups 2 and 3 can’t contain a string together, since they are mutually exclusive due to the “or”. The result is that the “40” is cut off at 401 to 409 and the “4” is cut off at 410 to 412.
Now the resulting line (1 to 12) should only be formatted under the condition, if no special character or the special character 999 was transmitted. Therefore "no_format" is set to "true", which ensures that the number is displayed left justified with the standard font, i.e. like a line that is transferred completely normally.
For formatting under the mentioned condition, this is defined with "cond_specialchar". It is again a regular expression, which this time only matches if the special character code is "-1" or "999".
If the condition is met, the line is formatted according to the standard modification formatting rules. This means that the largest possible font is used, the line is centered and the maximum possible spacing is used.
"cond_format_X_spacing" specifies a different spacing for all displays with a height of 32px or 26px.
The other parameters, i.e. the largest possible font and centering, are retained because they have not been overwritten.
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. |
optional |
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. |
optional |
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 |
<content> ... </content> |
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). |
optional |
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 |
<string> ... </string> |
Writes a string. See below. | As many as you want |
<tape> ... </tape> |
Draws a “barrier tape”. See below. | As many as you like |
<box> ... </box> |
Draws a rectangle with borders or filled. See below. | As many as you like |
<checkerboard> ... </checkerboard> |
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. |
<position> ... </position> |
See positioning of content elements (position, area). |
<area> ... </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 | |
---|---|---|
<inner> ... </inner> |
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. |
|
<outer> ... </outer> |
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. |
optional |
7.7 Drawing a checkboard pattern (checkerboard)
In a rectangular area.
7.7.1 Sub elements
Element | Desscription |
---|---|
<area> ... </area> |
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 |
---|---|
<x1>N</x1> <y1>N</y1> <x2>N</x2> <y2>N</y2> |
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 |
---|---|
<x>N</x> <y>N</y> |
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