Skip to content

Commit

Permalink
update schema examples from current state
Browse files Browse the repository at this point in the history
  • Loading branch information
@birkenfeld
birkenfeld committed Oct 15, 2024
1 parent 98ce452 commit 300bdae
Show file tree
Hide file tree
Showing 16 changed files with 591 additions and 367 deletions.
180 changes: 94 additions & 86 deletions rfcs/RFC-002-ontologies.rst → rfcs/RFC-002-schemata.rst
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
- Feature: Ontology Definitions and Repository
- Feature: Schema Definitions and Repository
- Status: Open
- Submit Date: <your date>
- Authors: Alexander Zaft <a.zaft@fz-juelich.de>, Enrico Faulhaber
Expand All @@ -11,30 +11,31 @@ Summary
=======

This RFC proposes a possibility to define the structure and meaning of SECoP
protocol elements at different levels, in a form that is both human readable and
protocol entities at different levels, in a form that is both human readable and
machine processable.

A central repository is also proposed describing the elements defined by the
A central repository is also proposed describing the entities defined by the
SECoP specification, providing this information to implementors.

Additional elements that are not yet in the specification, or too specialized to
Additional entities that are not yet in the specification, or too specialized to
be added to it, can be defined in the same way.


Goal
====

Many elements of the SECoP data model are defined in the specification. The goal
Many entities of the SECoP data model are defined in the specification. The goal
of this proposal is to formalize these definitions in a more machine-processable
form, while not losing human readability and too much flexibility.

These elements are:
These entities are:

- Interface classes and features
- Parameters, commands and properties
- Systems (see RFC 4)
- Data types
- Systems (see RFC-004)

The definitions for standard elements should be accessible in a central
The definitions for standard entities should be accessible in a central
repository. SECNodes should link to their respective specifications in order to
enable three things:

Expand All @@ -51,67 +52,81 @@ Definitions are given in the YAML format, in a form similar to object
descriptions in Kubernetes. Multiple definitions can be placed in the same file,
using the "document separator"s of YAML.

Each element has a few common fields:
Each entity has a few common fields:

``kind``
The kind of element, one of ``System``, ``Interface``, ``Feature``,
``Parameter``, ``Command``, ``Property``.
The kind of entity, one of ``Version``, ``System``, ``Interface``,
``Feature``, ``Parameter``, ``Command``, ``Property``, ``Datatype``.
``name``
The element's unique name.
The entity's unique name.
``version``
The version of the definition, as a simple integer.
``description``
A human-readable description. Optional.

Then, depending on the ``kind``, different keys can be present:

**For versions:**

TODO

**For interface classes and features:**

``base``
The base interface/feature this one is derived from.
``properties``
The properties that are required on this element.
The properties that are required on this entity.
``parameters``, ``commands``
The accessibles that are required on this element.
The accessibles that are required on this entity.

**For parameters:**

``readonly``
If the parameter should be readonly.
``datainfo``
Human readable explanation of the parameter's datainfo.
``properties``
The properties that are possible on this entity.
``optional``
If the parameter is optional when added in interfaces/features.

**For commands:**

``arguments``
``argument``
Human readable explanation of the arguments including datainfos.
``return``
``result``
Human readable explanation of the return value and its datainfo.
``properties``
The properties that are possible on this entity.
``optional``
If the command is optional when added in interfaces/features.

**For properties:**

``applies_to``
List of Kinds to which this property can be applied or ``SECNode``.
``datainfo``
Human readable explanation of the property's datainfo.
``optional``
If the property is optional.

**For datatypes:**

TODO

**For systems:**

``base``
The base system this one is derived from.
``modules``
A dictionary of module names and their definitions. Each item is
either a reference to an interface/feature definition.

When a new element is proposed, the ``version`` starts at 0. A version of 0
When a new entity is proposed, the ``version`` starts at 0. A version of 0
does not give a stability guarantee, unlike versions larger than 0. If an
element is accepted and introduced into the specification, the version is
entity is accepted and introduced into the specification, the version is
defined as 1. Changes to the interface afterwards bump the version number.

**XXX**

``optional``
If present and true, this element is optional.

As an example, a YAML description for some standard elements would look like this:
As an example, a YAML description for some standard entities would look like
this:

.. code:: yaml
Expand All @@ -129,8 +144,8 @@ As an example, a YAML description for some standard elements would look like thi
kind: Command
name: stop
version: 1
arguments: none
return: none
argument: none
result: none
description: |
Stop the current value-changing operation. If not driving, no effect.
Expand All @@ -144,12 +159,12 @@ As an example, a YAML description for some standard elements would look like thi
A base SECoP interface class for modules that can have their value changed,
reporting their status in the meantime.
parameters:
status:
# Refer to the element above to get the definition of this parameter.
definition: target:1
# A more specific description can be given in addition to the one already
# provided in the "target" element above.
description: ...
- target:
# Refer to this entity to get the definition of this parameter.
definition: target:1
# A more specific description can be given in addition to the one already
# provided in the "definition" entity above.
description: ...
---
kind: Interface
Expand All @@ -160,8 +175,7 @@ As an example, a YAML description for some standard elements would look like thi
A base SECoP interface class for modules whose values changes "slowly",
so that the change can be stopped.
commands:
stop:
definition: stop:1
- stop:1
---
kind: Feature
Expand All @@ -177,8 +191,7 @@ As an example, a YAML description for some standard elements would look like thi
SECoP target = ECS target - offset
parameters:
offset:
definition: offset:1
- offset:1
Example for a complete system that describes a simple power supply inspired by
issue 78:
Expand All @@ -190,7 +203,7 @@ issue 78:
name: quantity
version: 1
datainfo: string
applies_to: [Parameter]
optional: true
description: |
A hint of the physical quantity represented by this parameter.
Expand All @@ -202,47 +215,48 @@ issue 78:
A power supply consisting of current and voltage regulation modules.
The active module can be switched with the parameter `control_active`.
modules:
current:
definition: Drivable:1
description: Controls the current.
properties:
# This property has a general definition, but here the description
# defines a required value.
quantity:
definition: quantity:1
description: Must be set to "current".
parameters:
# This parameter is already defined by Drivable, but the required
# datainfo is made more concrete by this definition.
value:
datainfo: numeric, has unit Ampere
# This parameter is completely specific to this module.
voltage_limit:
description: |
Compliance voltage applied when supply is in current mode.
datainfo: numeric, has unit Volts
optional: true
power_limit:
description: |
Power limit applied when supply is in current mode.
datainfo: numeric, has unit Watts
optional: true
control_active:
definition: control_active:1
description: |
If true, power supply is in current mode.
Setting `voltage:control_active` resets this to false.
- current:
definition: Drivable:1
description: Controls the current.
properties:
# This property has a general definition, but here the description
# defines a required value.
- quantity:
definition: quantity:1
description: Must be set to "current".
parameters:
# This parameter is already defined by Drivable, but the required
# datainfo is made more concrete by this definition.
- value:
datainfo: numeric, has unit Ampere
# This parameter is completely specific to this module.
- voltage_limit:
description: |
Compliance voltage applied when supply is in current mode.
datainfo: numeric, has unit Volts
optional: true
- power_limit:
description: |
Power limit applied when supply is in current mode.
datainfo: numeric, has unit Watts
optional: true
- control_active:
definition: control_active:1
description: |
If true, power supply is in current mode.
Setting `voltage:control_active` resets this to false.
# similar for power, voltage
resistance:
definition: Readable:1
description: Readback for the measured resistance.
optional: true
parameters:
value:
datainfo: numeric, has unit Ohms.
quantity:
definition: quantity:1
description: Must be set to "resistance".
- resistance:
definition: Readable:1
description: Readback for the measured resistance.
optional: true
parameters:
value:
datainfo: numeric, has unit Ohms
properties:
quantity:
definition: quantity:1
description: Must be set to "resistance".
Disadvantages, Alternatives
Expand All @@ -258,13 +272,7 @@ should fulfill this condition, but one could think about a more generic
Alternatives
------------

The parameters are specified themselves, with a new ``kind: Parameter``, and
referenced in the module element, by a ``definition:`` and an (optional)
description. This reduces duplication, e.g. with the status parameter.

An option would be to allow both ways, either directly describing a
parameter or referencing one. The disatvantage with this would be that files
may change when a parameter has to be factored out after the fact.
None at the moment.


Open Questions
Expand Down
Loading

0 comments on commit 300bdae

Please sign in to comment.