diff --git a/docs-gen/content/common_rule_set/basics.md b/docs-gen/content/common_rule_set/basics.md index 9266ecb..40daaeb 100644 --- a/docs-gen/content/common_rule_set/basics.md +++ b/docs-gen/content/common_rule_set/basics.md @@ -5,16 +5,15 @@ weight: 1 --- ## Specification format -The syntax used to define the content of a HIM taxonomy is based on YAML and must comply to the -[YAML specification](https://yaml.org/). +The syntax used to define the content of a HIM taxonomy is based on YAML and must comply to the [YAML specification](https://yaml.org/). A HIM taxonomy may contain subtrees that are identical copies of each other, for example descriptions of doors in a vehicle. -In order not to have to repeat the content of the subtree multiple times, the subtree can be defined in a separate file, +In order not to have to repeat the content of the subtree multiple times, the subtree can be defined in a separate file, which can then be included into the main tree by the directive ``` #include [prefix] ``` -The optional [prefix] specifies a branch name to be prepended to all node names in the included file. +The optional [prefix] specifies a branch name to be prepended to all node names in the included file. The include directive may be used in files that are themselves included. Please note that, from a YAML perspective, the include directive is just another comment. @@ -52,14 +51,13 @@ NodeName: A node name is recommeded to be unique with the scope of the tree it is used in. The name shall follow the [Naming Conventions](#naming-conventions) -The qualified node name, which must be unique within the scope of the tree, are defined left-to-right of the concatenation of the node names, +The qualified node name, which must be unique within the scope of the tree, are defined left-to-right of the concatenation of the node names, starting from the root node of the tree and traversing the tree nodes to the node in focus, with a period (.) as delimiter between node names. An example of a qualified node name, which is called a path, is ``` a.b.c ``` -where a is the name of the root node, b is a child of a, -and the node in focus is c, a child of b. +where a is the name of the root node, b is a child of a, and the node in focus is c, a child of b. ### Node types @@ -71,14 +69,14 @@ while the node types specifi to a single information type are found in respectiv #### Struct node type -The 'struct' node type is used to define a structure data type that groups a number of fields. +The 'struct' node type is used to define a structure data type that groups a number of fields. An example is shown below. ```YAML NodeName: type: struct description: This is a struct node containing its mandatory metadata. ``` -This node type must have at least one child of node type property, and must not have children of any other node type. +This node type must have at least one child of node type property, and must not have children of any other node type. #### Property Node Type @@ -90,7 +88,7 @@ NodeName: datatype: "any supported datatype, including a reference to a struct definition" description: This is a property node containing its mandatory metadata. ``` -The 'datatype' metadata is mandatory for a property node. It may also have optional metadata such as unit, min, max, and allowed. +The 'datatype' metadata is mandatory for a property node. It may also have optional metadata such as unit, min, max, and allowed. A property node can only have a struct node as its parent, and must not have any children. @@ -131,9 +129,13 @@ See the [Value restrictions chapter](/hierarchical_information_model/common_rule A comment can be used to provide additional informal information on a branch. This could include background information on the rationale for the branch, references to related branches, standards and similar. Recommended to start with a capital letter and end with a dot (.). ### Instances -See the [Instances chapter](/hierarchical_information_model/common_rule_set/instances). +See the [Instances chapter](/hierarchical_information_model/resource_data_rule_set/vspec_extensions/instances). The `instances` metadata is only allowed in `branch` type nodes. +### Includes +See the [Includes chapter](/hierarchical_information_model/resource_data_rule_set/vspec_extensions/includes). +The `include` metadata is only allowed in `branch` type nodes. + ### Aggregate Defines whether or not this branch is an aggregate. If not defined, this defaults to ```false```. diff --git a/docs-gen/content/common_rule_set/includes.md b/docs-gen/content/common_rule_set/includes.md deleted file mode 100644 index 6302419..0000000 --- a/docs-gen/content/common_rule_set/includes.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Includes" -date: 2019-08-04T12:59:44+02:00 -weight: 6 ---- - -An include directive in a HIM file will read the file it refers to and the -contents of that file will be inserted into the current buffer in place of the -include directive. The included file will, in its turn, be scanned for -include directives to be replaced, effectively allowing formation of a tree of includedfiles. - -See the figurefor an example of such a tree. - -![Include directive](/hierarchical_information_model/images/include_directives.png?width=50pc)
-*Figure: Include directives* - - -The include directive has the following format: - - #include [prefix] - -The `````` part specifies the path, relative to the file with the ```#include``` directive, to the vspec file to replace the directive with. - -The optional ```[prefix]``` specifies a branch name to be -prepended to all signal entries in the included file. This allows a him file -to be reused multiple times by different files, each file specifying their -own branch to attach the included file to. - -An example of an include directive is: - - #include doors.him chassis.doors - -The ```doors.him``` section specifies the file to include. - -The ```chassis.doors``` section specifies that all signal entries in ```doors.him``` should have their names prefixed with ```chassis.doors```. - -If an included him file has node specifications that have -already been defined prior to the included file, the new specifications in the -included file will override the previous specifications. - -Complete subtrees can be reused by including them multiple times to different branches. diff --git a/docs-gen/content/common_rule_set/instances.md b/docs-gen/content/common_rule_set/instances.md deleted file mode 100644 index d4c59ad..0000000 --- a/docs-gen/content/common_rule_set/instances.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: "Instances" -date: 2019-07-31T15:27:36+02:00 -weight: 5 ---- - -It is not uncommon that when defining HIM taxonomies there is a need to repeat branches and data entries -when multiple instances of the same object occurs. -One mechanism to handle that is the [include directive](/hierarchical_information_model/common_rule_set/includes), -but that does not solve how to compactly describe a branch structure that uniquely enumerates multiple includes. -To avoid hard-coded repetitions of branches and data entries in the specification an instance-concept is supported. -Instances remove the need of repeating definitions, by defining at the node itself how often it occurs in -the resulting tree. -They are meant as a short-cut in the specification and can interpreted by tools that expands it to a full size tree. - -![Example tree before and after tool expansion](/hierarchical_information_model/images/instances.png?width=50pc) - -## Definition - -### How can I create instances for my `branch`? - -1. An instance can be defined in any branch node. -2. The instantiation is done for every node in the subtree of this branch node. -3. Instances are defined with the key-word `instances`, followed by its - definition, which can be either: - * a list of strings, where each element defines a single instance, e.g. - `['Left','Right']` results into two instances of every following - data entry in the path, named `Left` and `Right` - * a string, followed by a range defined through `[n,m]`, with `n,m` as integer and `n <= m`, - which defines the number of instances. - `Position[1,4]` results into 4 instances of every following - data entry in the path, named `Position1`, `Position2`, `Position3` - and `Position4`. It is in HIM recommended to use `1` as start index for the first instance. -4. If multiple instances occur in one node or on the path to a data entry, - the instances get combined, by the order of occurrence. Following the example above, - four position instances will be created for each of the 'Left' and 'Right' instances, - resulting into a total number of 8 instances of the subtree. - -### How can I exclude child-nodes from instantiation? - -Often it makes sense to instantiate all child-nodes of a branch. -But there are cases, when nodes are linked more to the general concept of -a subtree, but not to every the single instance of it. With examples from the VSS taxonomy, -this could be the `DoorCount`, -which would rather be `Door.Count`, `WheelDiameter`, which is rather linked -to an axle rather than the wheel itself or `Brake.FluidLevel` which is not -measured for a single break, but rather a system indication. - -To exclude a child-node from the instantiation of the *direct* parent node, set the -keyword `instantiate` to `false` (`true` by default). Please check the following -example for details. - -## Example - -Example from the VSS taxonomy: - -```YAML -# Cabin.vspec -Door: - type: branch - instances: - - Row[1,4] - - ["Left","Right"] - description: All doors, including windows and switches -#include SingleDoor.vspec Door - -Door.Count: - datatype: uint8 - type: attribute - default: 4 - instantiate: false - description: Number of doors in vehicle. -``` - - -```yml -# SingleDoor.vspec - -# -# Definition of a single door -# -IsOpen: - datatype: boolean - type: actuator - description: Is door open or closed -``` - -Results in the following dot-notated output: - -``` -Vehicle.Cabin.Door -Vehicle.Cabin.Door.Count -Vehicle.Cabin.Door.Row1 -Vehicle.Cabin.Door.Row1.Left -Vehicle.Cabin.Door.Row1.Left.IsOpen -Vehicle.Cabin.Door.Row1.Right -Vehicle.Cabin.Door.Row1.Right.IsOpen -Vehicle.Cabin.Door.Row2 -Vehicle.Cabin.Door.Row2.Left -Vehicle.Cabin.Door.Row2.Left.IsOpen -Vehicle.Cabin.Door.Row2.Right -Vehicle.Cabin.Door.Row2.Right.IsOpen -Vehicle.Cabin.Door.Row3 -Vehicle.Cabin.Door.Row3.Left -Vehicle.Cabin.Door.Row3.Left.IsOpen -Vehicle.Cabin.Door.Row3.Right -Vehicle.Cabin.Door.Row3.Right.IsOpen -Vehicle.Cabin.Door.Row4 -Vehicle.Cabin.Door.Row4.Left -Vehicle.Cabin.Door.Row4.Left.IsOpen -Vehicle.Cabin.Door.Row4.Right -Vehicle.Cabin.Door.Row4.Right.IsOpen -``` - -## Redefinition - -The default instantiation provided by a standard HIM tree can be redefined with -different instantiation information. If multiple definitions of a branch exist with different -instance definitions, then the last found definition will be used. -As an example, if only two rows of doors are needed, then a default HIM instance definition of four -can be overridden by redefining the Door branch as shown in the example below. - -```YAML -#Redefinition changing number of rows from 4 to 2 -#The redefinition must appear "after" the original definition -Vehicle.Cabin.Door: - type: branch - instances: - - Row[1,2] - - ["Left","Right"] - description: All doors, including windows and switches -``` - -## Recommendations - -The HIM design shall support configurability of multiple variants of a "standard" taxonomy. -This means that the default instantiation of a HIM taxonomy may not fit all needs of it. -The following is an example from the VSS taxonomy where parts of the windshield signals defined in `Body.vspec` are shown below. -VSS offers the possibility to control windshield heating separately for front and rear windshield, -and VSS also gives the possibility to report washer fluid level separately for each windshield. -This fits very well for a vehicle that has separate washer fluid containers for front and rear windshield -and that offers heating for both windshields. But that is not the case for all vehicles, -it is not even certain that all vehicles have two windshields. This sections gives recommendations on how -to use VSS for a vehicle if the VSS specification does not offer an exact match of the capabilities of the vehicle. - -```YAML -Windshield: - type: branch - instances: ["Front", "Rear"] - description: Windshield signals - -Windshield.Heating: - type: branch - description: Windshield heater signals - -Windshield.Heating.Status: - datatype: boolean - type: actuator - description: Windshield heater status. 0 - off, 1 - on - -Windshield.WasherFluid: - type: branch - description: Windshield washer fluid signals - -Windshield.WasherFluid.LevelLow: - datatype: boolean - type: sensor - description: Low level indication for washer fluid. True = Level Low. False = Level OK. -``` - -### Recommendation: Instance Mismatch - -If a vehicle does not have as many instances as specified in VSS then one -of the following methods are recommended: - -- Redefine the branch. If a vehicle for example does not have a rear windshield -then append a redefinition at the end of the VSS: - -```YAML -Vehicle.Body.Windshield: - type: branch - instances: ["Front"] - description: Windshield signals -``` - -- Accept that a `branch Vehicle.Body.Windshield.Rear` will exist in the generated VSS representation, - use mechanisms outside of VSS to ignore that branch - -### Recommendation: Features shared among instances - -If a feature is shared among instances, it is recommended to publish that feature for all concerned instances. - -Example: In VSS washer fluid can be handled separately for front and rear windshield. -If a vehicle use a common container serving both front and rear windshield, -then it is recommended that the vehicle report information on that container in both -`Vehicle.Body.Windshield.Front.WasherFluid.LevelLow` and `Vehicle.Body.Windshield.Rear.WasherFluid.LevelLow`. - -### Recommendation: Features lacking for some instances - -Not all instances in a vehicle might have the same features. If e.g. the front windshield -from the example above lack a heater, then it is recommended to use mechanisms outside of VSS -to ignore `Vehicle.Body.Windshield.Front.Heating`. diff --git a/docs-gen/static/images/include_directives.png b/docs-gen/static/images/include_directives.png index 28601d3..7e5b917 100644 Binary files a/docs-gen/static/images/include_directives.png and b/docs-gen/static/images/include_directives.png differ