Merge develop into main

.gitignore

@@ -8,3 +8,4 @@
 /language/example/kBus/generated
 /language/example/etherCAT/generated
 /language/example/showcase/generated
+/language/example/exhaustive/generated

README.md

@@ -1,44 +1,49 @@
-# bcs-engineering-dsl
+# BCS Engineering Framework
 
-## 1. Prerequisites
+## 1 Prerequisites
 
 - Windows with TcXaeShell Version 15.0 or higher
 
-## 2. Example
+## 2 Installation
 
-To run the example in the folder [language/example](language/example), you need to follow the following steps.
+To install the complete framework, you need to install three components:
 
-### 2.1 Generate the artifacts
+1. VS Code extension: `BCS Engineering DSL`
+2. `bcs-engineering-cli` - The CLI to generate the artifacts from the DSL files.
+3. `TcAutomation` - The tool to create and deploy the TwinCAT project from the generated artifacts.
 
-For this follow the installation instructions in the [bcs-engineering-dsl](language/README.md) README file.
+### 2.1 Install bcs-engineering-cli and VS Code Extension
+
+To install the `bcs-engineering-cli` and `BCS Engineering DSL` VS Code extension, follow the installation and usage instructions in the [README](language/README.md) file.
 
 ### 2.2 Install TcAutomation
 
-_TcAutomation_ is responsible for the creation of the corresponding TwinCAT project given the generated artifacts. To install it, you need to run the `TcAutomationInstaller.exe`.
+_TcAutomation_ is responsible for the creation and deployment of the corresponding TwinCAT project given the generated artifacts. To install it, you need to run the `TcAutomationInstaller.exe`.
 To create the installer, follow the steps described in the [TcAutomation](TcAutomation/README.md) README file.
 
-### 2.3 Check TcAutomation Installation
+#### Check TcAutomation Installation
 
 To check if _TcAutomation_ is installed correctly, you can run the following command in a command:
 
 ```bash
 TcAutomation --help
 ```
 
-### 2.5 BCS Engineering CLI
+## 3 Usage
+
+After installation, explore the [example](language/example) folder to get started with the framework. The examples demonstrate how to define control logic and hardware configurations using the BCS Engineering DSL. You can either generate some of the artifacts (ST and TwinCAT config files) without deployment or generate and deploy them to a Beckhoff device.
 
-#### 2.5.1 Generate
+#### 3.1 Generate
 
-To generate the artifacts, you can run the following command in the `language/example` folder:
+To generate the artifacts, you can run the following command in the `language/example` directory:
 
 ```bash
 bcs-engineering-cli beckhoff generate .\kBus\control.bcsctrl
 ```
 
-#### 2.5.2 Deploy
+#### 3.2 Deploy
 
-To deploy the generated artifacts, you can run the following command in the `language/example` folder.
-(Note: this command generates and deploys the artifacts)
+To generate and deploy the artifacts, you can run the following command in the `language/example` directory:
 
 ```bash
 bcs-engineering-cli beckhoff deploy .\kBus\control.bcsctrl

TcAutomation/README.md

@@ -1,16 +1,17 @@
-# Build
+# TcAutomation Deployment Tool
+
+## 1 Prerequisites
+
+- [Inno Setup](https://jrsoftware.org/isinfo.php)
+
+## 2 Build Project
 
 ```bash
 msbuild /p:Configuration=Release TcAutomation.csproj
 ```
 
-# Windows Installer
-
-## Pre-requisites
-- Build the project in Release mode.
-- [Inno Setup](https://jrsoftware.org/isinfo.php)
+## 3 Create Installer
 
-## Build
-- Open the `TcAutomation.iss` file in Inno Setup.
+- Open the [TcAutomationInstaller.iss](TcAutomationInstaller.iss) file within the Inno Setup.
 - Click the "Build/Compile" button (or press Ctrl+F9)."
-- The installer will be created in the `output` folder.
+- The installer will be created in the [output](output) folder.

language/README.md

@@ -1,35 +1,44 @@
 [![CI](https://github.com/elkoDev/bcs-engineering-dsl/actions/workflows/ci.yml/badge.svg)](https://github.com/elkoDev/bcs-engineering-dsl/actions/workflows/ci.yml)
 
-# 1. Setup
+# BCS Engineering DSL
 
-## 1.1 Install Dependencies
+## 1 Publishing
+
+### 1.1 Install Dependencies
 
 ```bash
 npm install
 ```
 
-## 1.2 Build
+### 1.2 Build
 
 ```bash
 npm run langium:generate && npm run build
 ```
 
-## 1.3 Generate Extension
+### 1.3 Generate Extension
 
 Before generating the extension, make sure to run the build commands first.
 
 ```bash
 vsce package
 ```
 
-## 1.4 Publish CLI
+### 1.4 Publish CLI
+NOTE: Previous versions have been published under the name `bcs-engineering-dsl` on my personal npm account. To avoid confusion, you might want to publish under a different name.
 
 ```bash
 npm login
 npm publish --access public
 ```
 
-## 1.5 Install CLI
+## 2 Installation
+
+### 2.1 Install VS Code Extension
+
+Right click on the `bcs-engineering-dsl-<version>.vsix` file and select `Install Extension VSIX`.
+
+### 2.2 Install the CLI:
 
 ```bash
 npm install -g bcs-engineering-dsl
@@ -41,28 +50,30 @@ or link the local version
 npm link
 ```
 
-# 2. Usage
+## 3 Usage
 
-## 2.1 Generate Code
+### 3.1 Generate Code
 
 ```bash
 bcs-engineering-cli beckhoff generate <path-to-bcsctrl-file>
 ```
 
-## 2.2 Generate Code and Deploy
+### 3.2 Generate Code and Deploy
 
 ```bash
 bcs-engineering-cli beckhoff deploy <path-to-bcsctrl-file>
 ```
 
 **NOTE:** The working directory will be set to the root of the provided file. This means that the .bcsctrl file can contain cross-references to other files in the same directory.
 
-## 2.3 Supported Target Platforms
+### 3.3 Supported Target Platforms
 
 Currently the following target platforms are supported:
 
-### 2.3.1 Beckhoff TwinCAT 3
+#### 3.3.1 Beckhoff
 
 In addition to the standard libraries provided by Beckhoff, the following libraries are supported:
 
-- `Tc3_DALI`
+- `Tc3_DALI`: Please note that this library integration is not fully tested.
+
+## 4 Future Work

language/example/showcase/showcase.bcsctrl

@@ -1,7 +1,23 @@
 control ShowcaseController {
-    var presenceSensor: BOOL;
-    var roomOccupancy: INT = 0;
-    unit CountPersonEntering once when (presenceSensor) {
-        roomOccupancy = roomOccupancy + 1;
+    enum OpMode {
+        Auto,
+        Manual,
+        Off
+    }
+    functionblock HeatingLogic {
+        inputs {
+            var iTemp: REAL;
+            var iMode: OpMode;
+        }
+        outputs {
+            var oHeating: BOOL;
+        }
+        logic {
+            oHeating = iMode == OpMode.Auto && iTemp < 20.5;
+        }
+    }
+    unit MorningWarmUp at TOD#06:00:00 {
+        var currentMode: OpMode = OpMode.Auto;
+        use HeatingLogic(iTemp: RoomSensor.Temperature, iMode: currentMode) -> HeatingActuator.IsActive;
     }
 }

language/example/showcase/showcase.bcshw

@@ -33,7 +33,7 @@ controller ShowcaseController {
         channels: 4
     }
 
-    portgroup TwoDigitalInputs {
+    portgroup Room1DigitalInputs {
         module: Zwei_Kanal_Digital_Eingang_Modul
         ioType: DIGITAL_INPUT
         channels: 2
@@ -50,7 +50,28 @@ controller ShowcaseController {
         ioType: ANALOG_OUTPUT
         channels: 4
     }
-}    
+
+    datapoint MotionSensor {
+        portgroup: Room1DigitalInputs
+        channels: {
+            channel Value: BOOL link "Channel 1^Input"
+        }
+    } 
+
+    datapoint RoomSensor {
+        portgroup: Room1DigitalInputs
+        channels: {
+            channel Temperature: REAL link "Channel 2^Input"
+        }
+    } 
+
+    datapoint HeatingActuator {
+        portgroup: TwoDigitalOutputs
+        channels: {
+            channel IsActive: BOOL link "Channel 1^Output"
+        }
+    } 
+}   
 
 network {
     hostname: "CX-301714"

language/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.22",
+  "version": "0.0.24",
   "name": "bcs-engineering-dsl",
   "displayName": "BCS Engineering DSL",
   "icon": "icon.png",

language/puml/bcs-control-metamodel.puml

@@ -154,9 +154,9 @@ package "Literals" {
 
 ' Abstract element for what can be referenced by name
 abstract class NamedElement
-NamedElement <|--- VarDecl
-NamedElement <|--- EnumDecl
-NamedElement <|--- Datapoint
+NamedElement <|-- VarDecl
+NamedElement <|-- EnumDecl
+NamedElement <|-- Datapoint
 
 ' ===== RELATIONSHIPS =====
 
@@ -213,9 +213,9 @@ UseStmt "1" *-- "1" UseOutput : useOutput
 InputMapping "1" ..> "1" VarDecl : inputVar
 UseOutput "1" *-- "0..1" SimpleUseResult : singleOutput
 UseOutput "1" *-- "0..*" MappingUseResult : mappingOutputs
-SimpleUseResult "1" ..> "1" VarDecl : targetOutputVar
+SimpleUseResult "1" ..> "1" Ref : target
 MappingUseResult "1" ..> "1" VarDecl : fbOutputVar
-MappingUseResult "1" ..> "1" VarDecl : targetOutputVar
+MappingUseResult "1" ..> "1" Ref : target
 EdgeStmt "1" *-- "1" Ref : signal
 
 ' --- Expressions ---

language/src/cli/cli-util.ts

@@ -13,14 +13,6 @@ import {
   isHardwareModel,
 } from "../language/generated/ast.js";
 
-/**
- * Read a requirement document with the complete workspace (with requirements and
- * tests) located in the folder of the file.
- * @param fileName the main requirement model file
- * @param services the language services
- * @returns a tuple with the document indicated by the fileName and a list of
- *          documents from the workspace.
- */
 export async function extractDocuments(
   fileName: string,
   services: LangiumCoreServices,

language/src/cli/main.ts

@@ -14,8 +14,6 @@ export default function () {
   program.version(pkg.version);
 
   program.addCommand(defineBeckhoffSubcommands());
-  // program.addCommand(defineSiemensSubcommands());
-  // program.addCommand(defineKnxSubcommands());
 
   program.parse();
 }

language/src/cli/platform/beckhoff/application/main-program-generator.ts

@@ -80,7 +80,6 @@ export class MainProgramGenerator {
     );
 
     const declFilePath = path.join(this.destination, `MAIN_decl.st`);
-    // Ensure the destination directory exists
     fs.mkdirSync(this.destination, { recursive: true });
     fs.writeFileSync(declFilePath, declContent);
     const implFilePath = path.join(this.destination, `MAIN_impl.st`);

language/src/cli/platform/beckhoff/application/qualified_reference_name.ts

@@ -25,9 +25,11 @@ export function getReferenceName(ref: Reference<NamedElement>): string {
 
 /**
  * Check if a referenced element belongs to a control unit
- * This helps us determine if we need to qualify the variable name
+ * @param ref Reference to check
+ * @return Tuple where the first element indicates if it's in a control unit,
+ *         and the second element is the control unit name or null
  */
-export function isControlUnitVariable(
+function isControlUnitVariable(
   ref: Reference<NamedElement>
 ): [boolean, string | null] {
   const container = ref?.ref?.$container;