diff --git a/specification/source/codeGeneration.rst b/specification/source/codeGeneration.rst index 508924a7..ae5bae9e 100644 --- a/specification/source/codeGeneration.rst +++ b/specification/source/codeGeneration.rst @@ -104,19 +104,25 @@ Translation of a Control Sequence using a JSON Intermediate Format Control companies that choose to not use C-code generation or the FMI standard to execute CDL-compliant control sequences can develop translators from -CDL to their native language. To aid in this process, a CDL to JSON translator -can be used. Such a translator is currently being developed at -https://github.com/lbl-srg/modelica-json. -This translator parses CDL-compliant control sequences to a JSON format. -The parser generates the following output formats: - -1. A JSON representation of the control sequence, -2. a simplified version of this JSON representation, and -3. an html-formated documentation of the control sequence. +CDL to their native language. To aid in this process, an intermediate +Control eXchange Format (CXF) can be used. CXF is a JSON-LD representation +of a CDL sequence, serialized in JSON. `Modelica-json `_ +is a reference implementation of such a CDL to CXF translator. +This translator first parses CDL-compliant control sequences to a abstract +syntax tree in JSON format and then generates a CXF representation from it. +The ``modelica-json`` tool can also parse Modelica code and it +can generate the following output formats: + +1. A JSON representation of the control sequence (CDL) or the Modelica + file(``raw-json``), +2. A simplified version of this JSON representation (``json``), +3. A semantic model from the control sequnce or the Modelica file + (``semantic``) and +4. A CXF representation of the control sequence (``cxf``). To translate CDL-compliant control sequences to the language that is used -by the target building automation system, the simplified JSON representation -is most suited. +by the target building automation system, the Control eXchange Format (CXF) +representation is most suited. As an illustrative example, consider the composite control block shown in :numref:`fig_custom_control_block` and reproduced in @@ -142,17 +148,16 @@ Executing the command .. code-block:: bash - node modelica-json/app.js -f CustomPWithLimiter.mo -o json-simplified + node modelica-json/app.js -f CustomPWithLimiter.mo -o cxf -will produce a file called ``CustomPWithLimiter-simplified.json`` that +will produce a file called ``CustomPWithLimiter.jsonld`` that looks as follows: -.. literalinclude:: img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter-simplified.json +.. literalinclude:: img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter.jsonld :language: json :linenos: -Note that the graphical annotations are not shown. -The JSON representation can then be parsed and converted to another block-diagram +The representation can then be parsed and converted to another block-diagram language. Note that ``CDL.Reals.MultiplyByParameter`` is an elementary CDL block (see :numref:`sec_ele_blo`). diff --git a/specification/source/img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter-simplified.json b/specification/source/img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter-simplified.json deleted file mode 100644 index d8d2e4b7..00000000 --- a/specification/source/img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter-simplified.json +++ /dev/null @@ -1,96 +0,0 @@ -[ - { - "modelicaFile": "CustomPWithLimiter.mo", - "topClassName": "CustomPWithLimiter", - "comment": "Custom implementation of a P controller with variable output limiter", - "public": { - "parameters": [ - { - "className": "Real", - "name": "k", - "comment": "Constant gain", - "annotation": { - "dialog": { - "tab": "General", - "group": "Parameters" - } - } - } - ], - "models": [ - { - "className": "CDL.Interfaces.RealInput", - "name": "yMax", - "comment": "Maximum value of output signal" - }, - { - "className": "CDL.Interfaces.RealInput", - "name": "e", - "comment": "Control error" - }, - { - "className": "CDL.Interfaces.RealOutput", - "name": "y", - "comment": "Control signal" - }, - { - "className": "CDL.Reals.MultiplyByParameter", - "name": "gain", - "comment": "Constant gain", - "modifications": [ - { - "name": "k", - "value": "k", - "isFinal": true - } - ] - }, - { - "className": "CDL.Reals.Min", - "name": "minValue", - "comment": "Outputs the minimum of its inputs" - } - ] - }, - "info": "\n

\nBlock that outputs y = min(yMax, k*e),\nwhere\nyMax and e are real-valued input signals and\nk is a parameter.\n

\n", - "connections": [ - [ - { - "instance": "yMax" - }, - { - "instance": "minValue", - "connector": "u1" - } - ], - [ - { - "instance": "e" - }, - { - "instance": "gain", - "connector": "u" - } - ], - [ - { - "instance": "gain", - "connector": "y" - }, - { - "instance": "minValue", - "connector": "u2" - } - ], - [ - { - "instance": "minValue", - "connector": "y" - }, - { - "instance": "y" - } - ] - ] - } -] \ No newline at end of file diff --git a/specification/source/img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter.jsonld b/specification/source/img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter.jsonld new file mode 100644 index 00000000..9bf2f06a --- /dev/null +++ b/specification/source/img/codeGeneration/CustomPWithLimiter/CustomPWithLimiter.jsonld @@ -0,0 +1,130 @@ +{ + "@context": { + "S231P": "https://data.ashrae.org/S231P#" + }, + "@graph": [ + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter", + "@type": "S231P:Block", + "S231P:containsBlock": [ + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.gain" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.minValue" + } + ], + "S231P:hasInput": [ + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.e" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.yMax" + } + ], + "S231P:hasOutput": { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.y" + }, + "S231P:hasParameter": { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.k" + }, + "S231P:label": "CustomPWithLimiter" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.e", + "@type": "S231P:RealInput", + "S231P:accessSpecifier": "public", + "S231P:description": "Control error", + "S231P:graphics": "{\"Placement\":{\"transformation\":{\"extent\":[{\"x\":-140,\"y\":-60},{\"x\":-100,\"y\":-20}]}}}", + "S231P:isConnectedTo": { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.gain.u" + }, + "S231P:label": "e" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.gain", + "@type": "https://data.ashrae.org/S231P#Buildings.Controls.OBC.CDL.Reals.MultiplyByParameter", + "S231P:accessSpecifier": "public", + "S231P:description": "Constant gain", + "S231P:graphics": "{\"Placement\":{\"transformation\":{\"extent\":[{\"x\":-60,\"y\":-50},{\"x\":-40,\"y\":-30}]}}}", + "S231P:hasInstance": [ + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.gain.k" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.gain.u" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.gain.y" + } + ], + "S231P:label": "gain" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.gain.k", + "S231P:isFinal": true, + "S231P:value": "k" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.gain.y", + "S231P:isConnectedTo": { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.minValue.u2" + } + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.k", + "@type": "S231P:Parameter", + "S231P:accessSpecifier": "public", + "S231P:description": "Constant gain", + "S231P:isOfDataType": { + "@id": "S231P:Real" + }, + "S231P:label": "k", + "S231P:value": 2 + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.minValue", + "@type": "https://data.ashrae.org/S231P#Buildings.Controls.OBC.CDL.Reals.Min", + "S231P:accessSpecifier": "public", + "S231P:description": "Outputs the minimum of its inputs", + "S231P:graphics": "{\"Placement\":{\"transformation\":{\"extent\":[{\"x\":20,\"y\":-10},{\"x\":40,\"y\":10}]}}}", + "S231P:hasInstance": [ + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.minValue.u1" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.minValue.u2" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.minValue.y" + } + ], + "S231P:label": "minValue" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.minValue.y", + "S231P:isConnectedTo": { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.y" + } + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.y", + "@type": "S231P:RealOutput", + "S231P:accessSpecifier": "public", + "S231P:description": "Control signal", + "S231P:graphics": "{\"Placement\":{\"transformation\":{\"extent\":[{\"x\":100,\"y\":-10},{\"x\":120,\"y\":10}]}}}", + "S231P:label": "y" + }, + { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.yMax", + "@type": "S231P:RealInput", + "S231P:accessSpecifier": "public", + "S231P:description": "Maximum value of output signal", + "S231P:graphics": "{\"Placement\":{\"transformation\":{\"extent\":[{\"x\":-140,\"y\":20},{\"x\":-100,\"y\":60}]}}}", + "S231P:isConnectedTo": { + "@id": "http://example.org#FromModelica.CustomPWithLimiter.minValue.u1" + }, + "S231P:label": "yMax" + } + ] +}