RBA¶

Rule Based Arbitrator (RBA) decides which of the content to display when a large number of contents to be displayed on the cockpit display device (CID, meter, HUD, etc.) occur simultaneously under a certain rule (arbitration).

1. Overview¶

1.1 Purpose of this document¶

This document describes the syntax of the Rule-based Arbitration Model.

1.2 Basic syntax¶

The basic syntax of the Rule-based Arbitration Model is as follows.

Define the properties of the model element in {} after declaration of Model element keyword,　Model element ID. Each property depends on the element. The properties of the model element may also define other model elements.

1.3 Relationship between files and Model definitions¶

The Rule-based Arbitration Model can be defined in multiple files. (The extension of the file will be ".rba") Firstly, define the Package model element in the file.

Areas.rba

Package AreasPackage {

}

Package ContentsPackage {

}

1.4 Structure of Rule-based Arbitration Model¶

The elements of the Rule-based Arbitration Model are as follows. Each inheritance relationship between elements is defined and expresses elements that can be described in PackagableElement.

1.5 Notation of Syntax Definition¶

For Model element

syntax:

Package [ID] {
  description: [String]
  [PackagableElement]
}

Description:

The multiplicity is expressed as follows:

Description of [] notation is as follows:

2. Common¶

2.1 Package¶

The Package element is the root element in the file. It has PackagableElement as a Child element and groups PackagableElements in arbitrary units.

syntax:

Package [ID] {
  description: [String]
  [PackagableElement]
}

Description example:

Package SamplePackage {
    description: "This is a sample Packege"
    Area SampleArea {
        arbitrationPolicy: DEFAULT
        sizeReference: SampleSize1
        visibility: NONE_VALUE
        zorder: 3
    }
    ViewContent SampleContent {
        allocatable: [SampleArea1]
        State NORMAL {
            priority: STANDARD_VALUE
        }
    }
}

2.2 Size¶

Size is the size of Area and ViewContent.

Syntax:

Size [ID] {
  description: [String]
  width: [Number]
  height: [Number]
}

Description example:

Size ScreenSize {
    description: " Screen size"
    width: 200
    height: 200
}

2.3 Project¶

The Project element is an element that can be defined only once in one project. Like The Package element, it can be defined directly under the file.

Syntax:

Project {
  version: [String]
}

Description example:

Project {
    version: "version 1.0"
}

3. Area¶

Area is a frame to display the ViewContent on the screen. Only one ViewContent is allocated to one Area at most. Since Arbitration is executed for each Area, the Arbitration Policy is defined.

Syntax:

Area [ID] {
  description: [String]
  arbitrationPolicy: [DEFAULT | FIRST_COME_FIRST | LAST_COME_FIRST | PRIORITY_FIRST_COME_FIRST | PRIORITY_LAST_COME_FIRST]
  [[Size]| sizeReference:[ID of Size]]
  [visibility|priority]:[Number|Expression]
  zorder:[Number|Expression]
}

Types of Arbitration Policy

Description example:

Area SampleArea {
    description: "This is a sample Area."
    arbitrationPolicy: DEFAULT
    Size Default {
        width: 200
        height: 150
    }
    sizeReference: SampleSize1
    visibility: NONE_VALUE
    zorder: 3
}

4. Value / Z order definition¶

Values (visibility or priority) of area is the order of arbitrating of the area. The higher is arbitrated first. You can describe only one of the visibility or priority. For the Z order (zorder), the higher one will be on the front of the screen. You can define values absolutely by number or define relatively to other areas by expressions. You can use comparison operators (> and <), equality operator (=) and That-of operator for the expressions.

• Description example of value : Visibility of SampleArea2 is 10, zorder is 5.

  Area SampleArea2 {
      visibility: 10
      zorder: 5
  }
  

• Description example of comparison operator: Priority of SampleArea1 is greater than SampleArea2. Zorder of SampleArea1 is less than SampleArea3.

  Area SampleArea1 {
      priority: > That-of SampleArea1
      zorder: < That-of SampleArea3
  }
  

• Description example of range: Visibility of SampleArea1 is greater than 1 and less than SampleArea2. Zorder of SampleArea1 is greater than SampleArea3 and less than SampleArea4.

  Area SampleArea1 {
      visibility: (> 1 AND < That-of SampleArea2)
      zorder: (> That-of SampleArea3 AND < That-of SampleArea4)
  }
  

• Description example of equality operator:

  Area SampleArea1 {
      visibility: = That-of SampleArea2
      zorder: = That-of SampleArea3 + That-of SampleArea2
  }
  

• Equality operator can be omitted.

  Area SampleArea1 {
      visibility: That-of SampleArea2
      zorder: That-of SampleArea3 + That-of SampleArea2
  }
  

5. ViewContent definition¶

5.1 ViewContent¶

ViewContent is an object to be displayed in the Area. ViewContent has multiple states. When ViewContent is allocated to an Area, active state of theViewContent is displayed. Define the Area which can display ViewContent to the ViewContent. You can define several Areas.

Syntax:

ViewContent [ID] {
  description: [String]
  allocatable: [ [ID of Area] | [ID of Set] ]
  [ViewContentState]
  [[Size]|sizeReference: [ID of Size]]
  loserType: [GOOD_LOSER | DO_NOT_GIVEUP_UNTIL_WIN | NEVER_GIVEUP]
}

Types of Action on lost

Description example:

ViewContent Power {
description: " Warning from power management"
  allocatable: [
    MessageArea, HUDMessageArea
  ]
  State Warning {
    priority: > That-of Power.Attention
  }
  State Attention {
    priority: > That-of TEL.Incoming
  }
Size Default {
description: "Default size"
width: 200
height: 200
}
  sizeReference: InterruptMessageSize
  loserType: GOOD_LOSER
}

5.2 State(ViewContent)¶

State is the state of the ViewContent.

Syntax:

State [ID] {
  description: [String]
  [priority|value]: [Number|Expression]
}

Description example:

State Warning {
  description: "Display warning message"
priority: > That-of Attention
}
State Attention {
  description: " Display attention message "
priority: > That-of TEL.Incoming
}

6. Priority definition¶

Define the priority of Content to the State under ViewContent or SoundContent (hereinafter, Content). The priority is used when the area / zone arbitration policy is "Priority and First Come First Arbitration" or "Priority and Last Come First Arbitration", the higher one is allocated first. Values can be defined absolutely by number or relative to other areas by expressions. You can describe only one of the visibility or priority. You can use comparison operators (> and <), equality operator (=) and That-of operator for the expressions.

• Description example of value: Priority of Warning is 10.

  State Warning {
    description: " Display warning message "
  priority: 10
  }
  

• Description example of comparison operator: Value of Warning is greater than Attention.
  Value of Attention is greater than State Incoming of TEL of other Content.
  Value of Notice is less than Attention.
  ※When referring to the State of another Content, refer to the Content ID and State ID by connecting with “.”.

  State Warning {
    value: > That-of Attention
  }
  
  State Attention {
    value: > That-of TEL.Incoming
  }
  
  State Notice {
    value: < That-of Attention
  }
  

• Description example of range: Priority of Attention is greater than Incoming of TEL and less than Warning.
  ※When referring to the State of another Content, refer to the Content ID and State ID by connecting with “.”.

  State Attention {
    priority: (> That-of TEL.Incoming AND < That-of Warning)
  }
  

• Description example of equality operator:Value of Attention is equal to State Incoming of TEL of other Content.

  State Attention {
    priority: = That-of TEL.Incoming
  }
  

• Equality operator can be omitted.

  State Attention {
    priority: That-of TEL.Incoming
  }
  

7. Screen layout definition¶

7.1. Display¶

Display represents one screen. When defined more than one, it will be Multi-screen layout. The Display defines the set of Areas to be allocated on the screen.

Syntax:

Display [ID] {
  description: [String]
  [CompositeArea]
  [[Size]|sizeReference:[ID of Size]]
}

Description example:

Display METER {
    description:"Meter display definition"
    Size FULLSCREEN {
        width: 500
        height: 400
    }
    CompositeArea METER_Root {
        layout: FixedPositionLayout {
            PositionContainer {
                x: 100
                y: 100
                basePoint: LEFT_TOP
                areaReference: SpeedMeterArea
            }
        }
    }
}

7.2. CompositeArea¶

CompositeArea specifies an Area that becomes a component of Display.

Syntax:

CompositeArea [ID] {
  description: [String]
  layout: [FixedPositionLayout]
}

Description example:

CompositeArea METER_Root {
    description:" Definition of Area’s layout method"
    layout: FixedPositionLayout {
        PositionContainer {
            x: 100
            y: 100
            basePoint: LEFT_TOP
            areaReference: SpeedMeterArea
        }
    }
}

7.3. FixedPositionLayout¶

FixedPositionLayout declares that areas are laid out with fixed values. The specific position define by PositionContainer.

Syntax:

FixedPositionLayout {
  [PositionContainer]
}

FixedPositionLayout {
    PositionContainer {
        x: 100
        y: 100
        basePoint: LEFT_TOP
        areaReference: SpeedMeterArea
    }
}

7.4. PositionContainer¶

PositionContainer specifies the display position of the Area.

syntax:

PositionContainer {
  x: [Number]
  y: [Number]
  basePoint: [Value]
  areaReference: [ID of Area]
  [Offset]
}

Description example:

FixedPositionLayout {
    PositionContainer {
        x: 100
        y: 100
        basePoint: LEFT_TOP
        areaReference: SpeedMeterArea
        Offset { x:-50 y:20 sizeReference: SpeedMeterArea }
    }
}

7.5. Offset¶

Offset is the offset position for each size.

Syntax:

Offset {
  description: [String]
  x: [Number]
  y: [Number]
  sizeReference: [ID of Size]
}

Description example:

Offset {
description:"Offset"
    x: 100
    y: -50
    sizeReference: SpeedMeterSize
}

8. Constraint defination¶

Constraints can be defined according to the state of the Area/Zone and the state of the ViewContent/SoundContent. The syntax can be used for Constraints is shown below.

• State reference of Area:

• State reference of ViewContent:

• Scene reference:

• Stereotyope:

• Operator:

• Quantization symbol:

• Built-in defined Expression:

The syntax precedence and associativity are shown below:

8.1 Constraint¶

Constraint describes constraint expressions. There are two types of constraint expressions Runtime constraints and Offline constraints. A Runtime constraint is a constraint expression that should be be true at the time of arbitration and controls the behavior of arbitration. An Offline constraint is a constraint expression that should be satisfied after arbitration and tests the arbitration result.

Syntax:

Constraint [ID] {
  description: [String]
  runtime: [true|false]
  [expression]
}

Description example

• AND/ OR/ Negation
  In the constraint expression, it is possible to express logical AND, logical OR, negation, which is a general logical operator, with AND, OR, and !. By using () you can also use in combination.

Example: Content1 is displayed or Content2 and Content3 are not displayed at the same time.

Constraint SampleConstraint1 {
runtime: true
Content1.isVisible() OR !(Content2.isVisible() AND Content3.isVisible())
}

Constraint SampleConstraint1 {
    description: "Sample Constraint Expression"
    runtime: true
    SampleContent1.isVisible() OR !SampleContent2.isVisible()
}

• Implication

Implications are false only if the left-hand side is true and the right-hand side is false, otherwise it is true.

Example: SampleContent4 is displayed if there is a request of SampleContent4.

Constraint SampleConstraint3 {
    runtime: true
    SampleContent4.isActive() -> SampleContent4.isVisible()
}

Example: If SampleArea1 displays SampleContent3, SampleArea2 does not display SampleContent3.

Constraint SampleConstraint2 {
    runtime: true
    (SampleArea1.displayingContent() == SampleContent3)
-> !(SampleArea2.displayingContent() == SampleContent3)
}

Example: If the value of the content displayed on SampleArea1 is higher than the value of the content displayed in SampleArea2, hide SampleArea2.

Constraint SampleConstraint2 {
    runtime: true
    (SampleArea1.contentValue() > SampleArea2.contentValue())
-> SampleArea2.isHidden())
}

Example: If the value of property1 of the information received from other RBAModel (Project) is 1, Content10 is not displayed.

Constraint SampleConstraint {
  (SampleScene1.isOn() AND SampleScene1.property1.get() = 1)
    -> ! Content10.isVisible()
}

• For-All

For-All targets a set, and it is true if all element of the set satisfies a lambda expression ({element name declaration | element condition}). For the set, you can specify a defined set or an One-time set. (Refer to “Group definition” for more informations.)
Example: If SampleContent1 is displayed, all Areas of AreaGroup1 is not displayed.
It is assumed that "AreaGroup1" is defined as AreaSet.

Constraint SampleConstraint {
    runtime: true
    SampleContent1.isVisible() ->
For-All AreaGroup1 { x | x.isHidden() }
}

• Exists

Exists targets a set, and it is true if even one element of the set satisfies a Lambda expression ({element name declaration | element condition}).
For the set, you can specify a defined set or an One-time set. (Refer to “Group definition” for more informations.)
Example: If any Content of ContentGroup1 is displayed, all Areas of AreaGroup1 is not displayed.
It is assumed that "ContentGroup1" is defined as ContentSet.
It is assumed that "AreaGroup1" is defined as AreaSet.

Constraint SampleConstraint {
    runtime: true
    Exists ContentGroup1{ x | x.isVisible() } ->
For-All AreaGroup1 { x | x.isHidden() }
}

• IF-THEN-ELSE Example: If the scene is SampleScene1, SampleContent4 is displayed, otherwise SampleContent4 is not displayed.

Constraint SampleConstraint4 {
    runtime: true
    IF(SampleScene1.isOn())
    THEN
        SampleContent4.isVisible()
    ELSE
        !SampleContent4.isVisible()
}

• (pre) Example: If SampleContent 1 is displayed (before arbitration), SampleContent 2 is not displayed.

  Constraint SampleConstraint {
      runtime: true
  (pre)SampleContent1.isVisible() -> !SampleContent2.isVisible()
  }
  

• HasComeEarlierThan/HasComeLaterThan Example: If request SampleContent 1 has come earlier then SampleContent 2, SampleContent 2 does not displayed.

  Constraint SampleConstraint {
      runtime: true
  SampleContent1.hasComeEarlierThan(SampleContent2) -> !SampleContent2.isVisible()
  }
  

  Below constraint behave as same as above.

  Constraint SampleConstraint {
      runtime: true
  SampleContent2.hasComeLaterThan(SampleContent1) -> !SampleContent2.isVisible()
  }
  

8.2 Syntax sugar¶

This syntax sugar simplifies the constraint expressions and improves their readability. You can use them like the existing constraint expressions. Below are the syntax sugars that can be used.

• Inequality（!=）
  It means that the left side value and the right side value are not equal. You can use this to compare objects. True if the left side value and the right side value are not equal. The types of expressions on the left and the right sides must match.

*ECE: Equivalent constraint expression

Description example: The ViewContent allocated to AreaA is not Content1.

• Allocation of Area/Zone
  It indicates that ViewContent/SoundContent is allocated to the Area/Zone. True if theViewConten/SoundContentt is allocated to the Area/Zone.

Description example: The Content1 is allocated to the AreaA.

• Allocation changing of Area/Zone
  It indicates a changing of the ViewContent’s/SoundContent’s allocated to the Area/Zone. True if the changing happens.

Description example: The ViewContent allocated to AreaA has changed.

• Changing of a content allocated to Area/Zone
  It indicates whether a ViewContent/SoundContent allocated to the Area/Zone has changed to the specified ViewContent/SoundContent.True if the changing happens

Description example: A ViewContent allocated to the AreaA has changed to Content1.

• Displaying in the Area
  It indicates whether the ViewContent displayed or not in the Area. True if the ViewContent is displayed in the Area.

Description example: The Content1 is displayed in the AreaA.

• Display changing of the Area
  It indicates whether the display of the Area changes or not. True if the change happens.

Description example: The display of the AreaA has changed.

• Changing of the displayed ViewContent to the specified ViewContent
  It indicates whether the ViewContent displayed in the Area has changed to anther specified ViewContent. True if the change happens.

Description example: A ViewContent displayed in the AreaA has changed to another Content1.

• Hide a lower priority Area
  Compare the two Areas and hide the Area displaying a ViewContent with lower priority.

Description example: AreaA and AreaB are compared to hide the Area which displays a ViewContent with lower priority.

9. Group definition¶

9.1 AreaSet¶

When dealing with multiple Areas in the Constraint expression, in order to describe it simply, you can define multiple Areas together in one group.

Syntax:

AreaSet [ID] {
  description: [String]
  target: [ [ID of Area] ]
}

Description example:

AreaSet MainScreen {
    description: "Area constituting the main screen"
    target: [SampleArea, SampleArea1, OtherAreaSet]
}

9.2 ViewContentSet¶

When dealing with multiple ViewContents in the Constraint expression, in order to describe it simply, you can define multiple ViewContents together in one group.

Syntax:

ViewContentSet [ID] {
  description: [String]
  allocatable: [ [ID of Area] ]
  target: [ [ID of ViewContent] ]
}

Description example:

ViewContentSet InterruptContent{
  allocatable: [
    MessageArea, HUDMessageArea, InterruptAreaGroup
  ]
  target: [
    TEL,Power, ViewContentGroup
  ]
}

9.3 One-time Set¶

Specify an set in the For-All or the Exists constraint, you can define the One-time set.

Syntax:

{ [ID] }

• Description example: Define the One-time set as AreaSet.

  Constraint SampleConstraint {
      runtime: true
      SampleContent1.isVisible() ->
  For-All {Area1, Area2, Area3} { x | x.isHidden() }
  }
  

• Description example: Define the One-time set as ViewContentSet.

  Constraint SampleConstraint {
      runtime: true
      Exists {ViewContent1, ViewContentSet1} { x | x.isActive() -> x.isVisible() }
  }
  

10. Scene definition¶

10.1 Scene¶

Scene comprehensively expresses the state at the time including the system, and it is used to switch the status of Area/Zone, View/Sound Content by Scene. You can also define the Global scene and share the results of arbitration among multiple RBA Models (Projects).

Syntax:

Scene [ID] {
  description: [String]
  global: [true|false]
  [Property]
}

Description example:

Scene AutoDrivingScene {
  description: "In auto driving mode"
}

Scene DisplayEventNotification {
  global: true
  int OverallPriority: 6
  int RiskSeverity: 3
  int RiskMargin: 1
}

10.2 Property¶

Property is arbitrary properties which is defined in the Scene.

Syntax:

int [String]: [Number]

Description example:

int RiskSeverity: 3

11. Stereotype¶

Syntax:

StereoType<[Target Model Name]> [ID] ([valiable]) @BEGIN@
description: [String]
    [Propaties of Element]
@END@

Description example:

Stereotype<ViewContent> display_warnning (name,allocatable,priority) @BEGIN@
    description: “@{name}”
    allocatable: [@{allocatable}]
    Size WarnSize {
        width: 300
        height: 100
    }
    State NORMAL { piority: @{priority} }

@END@

12. Tag¶

Syntax:

<<[Stereotype ID]>> | <<[Stereotype ID]>>{“[String]”}

Description example:

ViewContent Warning_1 {
    <<display_warning>>{ “Warning_01”,”Area1”,“1” }
}

ViewContent Warning_2 {
    <<display_warning>>{ “Warning_02”,”Area2”,”2” }
}

Stereotype<ViewContent> display_warnning (name,allocatable,priority) @BEGIN@
    description: “@{name}”
    allocatable: [@{allocatable}]
    Size WarnSize {
        width: 300
        height: 100
    }
    State NORMAL { piority: @{priority} }
@END@

Generate .json from .rba file¶

Download prebuilt package

• If some errors occur, RBAModel.json is not generated (exit code 1).

  java -cp ./ -jar JSONGenerator.jar "[path to model directory]" "[path to output directory]"
  

Example:

• RBAModel.json file is generated in directory same as JSONGenerator.jar

  java -cp ./ -jar JSONGenerator.jar "./RBAModel.rba"
  

• RBAModel.json file is generated in ~/ directory

  java -cp ./ -jar JSONGenerator.jar "./RBAModel.rba" "~/"
  

  Note: For the reference .rba file is given under the path prebuilt package/sample_model