Merge develop into main

README.md

@@ -4,7 +4,7 @@
 
 ## 1 Prerequisites
 
-- Windows with TcXaeShell Version 15.0 or higher
+- Windows with TcXaeShell Version 15.0 (other versions have not been tested)
 
 ## 2 Installation
 

TcAutomation/README.md

@@ -3,6 +3,7 @@
 ## 1 Prerequisites
 
 - [Inno Setup](https://jrsoftware.org/isinfo.php)
+- TwinCAT XAE Shell 15.0 properly installed and configured (see [TwinCAT Setup Guide](TWINCAT_SETUP.md))
 
 ## 2 Build Project
 
@@ -15,3 +16,38 @@ msbuild /p:Configuration=Release TcAutomation.csproj
 - 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](output) folder.
+
+## 4 CLI Usage
+
+**Note:** You typically don't call `TcAutomation.exe` directly. Instead, use the BCS Engineering DSL CLI tool:
+
+```bash
+bcs-engineering-cli beckhoff deploy <file>
+```
+
+The `deploy` command internally invokes `TcAutomation.exe` with the appropriate parameters. However, if you need to call it manually, the following options are available:
+
+### Command Line Options
+
+| Option            | Required | Default                                                             | Description                                        |
+| ----------------- | -------- | ------------------------------------------------------------------- | -------------------------------------------------- |
+| `--workspace`     | Yes      | -                                                                   | Path to your project root (where generated/ lives) |
+| `--solution-name` | No       | `MyGeneratedSolution`                                               | Name of the TwinCAT solution                       |
+| `--project-name`  | No       | `MyTwinCATProject`                                                  | Name of the Visual Studio project                  |
+| `--plc-name`      | No       | `MyPlcProject`                                                      | PLC project name                                   |
+| `--template-path` | No       | `C:\TwinCAT\3.1\Components\Base\PrjTemplate\TwinCAT Project.tsproj` | Path to your .tsproj template                      |
+| `--prog-id`       | No       | `TcXaeShell.DTE.15.0`                                               | ProgID to use when launching TwinCAT               |
+| `--ads-username`  | No       | `Administrator`                                                     | ADS username for remote connection                 |
+| `--ads-password`  | No       | `1`                                                                 | ADS password for remote connection                 |
+
+**Note:** If you're using a different TwinCAT version, you need to adjust the `--prog-id` parameter accordingly.
+
+### Example Usage
+
+```bash
+TcAutomation.exe --workspace "C:\Projects\MyProject"
+```
+
+```bash
+TcAutomation.exe --workspace "C:\Projects\MyProject" --solution-name "MySolution" --plc-name "MainPLC"
+```

TcAutomation/TWINCAT_SETUP.md

@@ -0,0 +1,118 @@
+# TwinCAT Setup Guide
+
+This guide covers the prerequisites and setup steps for working with TwinCAT XAE Shell 15.0.
+
+## 1 Prerequisites
+
+- Windows 10/11
+- TwinCAT XAE Shell Version 15.0 (compatibility with other versions has not been tested)
+  - **Tested Version**: TcXaeShell 15.0.34829.251 D15.9
+  - **Edition**: Express
+  - **Framework**: Microsoft .NET Framework 4.8.09221
+- 7-day trial license (or full license)
+
+## 2 TwinCAT Installation
+
+1. Download and install TwinCAT XAE Shell 15.0 from [Beckhoff's website](https://www.beckhoff.com/en-en/support/download-finder/software-and-tools/)
+2. Follow the installation wizard
+3. Verify the installation by checking the version (Help → About in TwinCAT XAE)
+
+### 2.1 Verified Components
+
+The framework has been tested with the following TwinCAT components:
+
+- **TwinCAT XAE Base**: 3.1.0.0
+- **TcXaeShell**: 1.15.0
+- **TcXaeHelper**: 4024.65.0.0
+- **TcXaeModules**: 4024.65.0.0 (TMC Editor, TMC Code Generator)
+- **TwinCAT Measurement**: 4.48.45.0
+- **TwinCAT Scope**: 4.48.92.0
+
+## 3 License Setup
+
+TwinCAT requires a valid license to run. For development and testing purposes, you can obtain a 7-day trial license:
+
+1. Create a new TwinCAT XAE project (File → New → Project → TwinCAT XAE Project)
+2. Add a PLC project to your solution
+3. Try to activate the configuration or switch to Run Mode
+4. A license popup will appear automatically, offering a 7-day trial license
+5. Follow the prompts to request and activate the trial license
+
+**Note:** The 7-day trial license needs to be renewed after expiration. You can renew it by repeating the process above.
+
+## 4 Hyper-V Compatibility Issue
+
+TwinCAT requires direct hardware access and **does not work with Hyper-V enabled**. If you're running Windows with Hyper-V or WSL2, you need to disable it.
+
+### 4.1 Disable Windows Core Isolation (Memory Integrity)
+
+Windows Core Isolation with Memory Integrity can interfere with TwinCAT. You need to disable it:
+
+1. Open Windows Security (Windows Defender)
+2. Go to **Device Security** → **Core Isolation Details**
+3. Turn off **Memory Integrity**
+4. Restart your computer
+
+
+### 4.2 Solution: Dual Boot Configuration
+
+Instead of permanently disabling Hyper-V, you can create a dual boot option that allows you to choose whether to boot Windows with or without Hyper-V.
+
+#### 4.2.1 Create Boot Entry (PowerShell Script)
+
+Run the following PowerShell script **as Administrator**:
+
+```powershell
+# Get GUID of current Windows boot entry
+$sourceGuid = "{current-boot-entry-guid}"  # Replace with your actual GUID
+$description = "Windows 11 - No Hyper-V (TwinCAT)"
+
+# Create new boot entry
+$bcdCopyOutput = bcdedit /copy $sourceGuid /d $description
+
+# Extract GUID
+if ($bcdCopyOutput -match "\{[0-9a-fA-F\-]+\}") {
+    $newGuid = $matches[0]
+
+    # Disable Hyper-V for this boot entry
+    bcdedit /set $newGuid hypervisorlaunchtype off
+
+    # Set boot timeout (optional)
+    bcdedit /timeout 5
+
+    # Display result
+    Write-Host "`n New boot entry successfully created:"
+    Write-Host "   Description: $description"
+    Write-Host "   GUID: $newGuid"
+    Write-Host "`n Select '$description' on next boot for TwinCAT without Hyper-V."
+} else {
+    Write-Host " Error: Could not extract GUID."
+}
+```
+
+#### 4.2.2 Find Your Current Boot GUID
+
+To find your current Windows boot entry GUID, run the following command as Administrator in PowerShell:
+
+```powershell
+bcdedit /enum
+```
+
+Look for the entry marked as `{current}` and note its GUID.
+
+#### 4.2.3 Result
+
+After running the script, you'll have two boot options:
+
+- **Windows 11** - Normal boot with Hyper-V enabled (for WSL2, Docker, etc.)
+- **Windows 11 - No Hyper-V (TwinCAT)** - Boot without Hyper-V for TwinCAT development
+
+Simply select the appropriate option when starting your computer.
+
+## 5 Verify Installation
+
+After setup, verify that TwinCAT is correctly installed:
+
+1. Open TwinCAT XAE (Visual Studio Shell)
+2. Check that TwinCAT system tray icon appears (orange/blue)
+3. Switch to Config Mode and then Run Mode to verify functionality

language/README.md

@@ -49,20 +49,37 @@ or link the local version
 npm link
 ```
 
-## 3 Usage
+## 3 Usage (Beckhoff)
 
 ### 3.1 Generate Code
 
 ```bash
-bcs-engineering-cli beckhoff generate <path-to-bcsctrl-file>
+bcs-engineering-cli beckhoff generate <path-to-bcsctrl-file> [options]
 ```
 
+**Options:**
+
+- `-d, --destination <dir>` - Output directory for generated files
+- `-q, --quiet` - Suppress output (default: false)
+
 ### 3.2 Generate Code and Deploy
 
 ```bash
-bcs-engineering-cli beckhoff deploy <path-to-bcsctrl-file>
+bcs-engineering-cli beckhoff deploy <path-to-bcsctrl-file> [options]
 ```
 
+**Options:**
+
+- `--template-path <path>` - TwinCAT template path
+- `--solution-name <name>` - Solution name (default: `MyGeneratedSolution`)
+- `--project-name <name>` - Project name (default: `MyTwinCATProject`)
+- `--plc-name <name>` - PLC project name (default: `MyPlcProject`)
+- `--tc-exe <path>` - Path to TcAutomation executable (default: `TcAutomation.exe`, resolved from PATH)
+- `--ads-username <username>` - ADS username for remote connection (default: `Administrator`)
+- `--ads-password <password>` - ADS password for remote connection (default: `1`)
+- `-d, --destination <dir>` - Output directory for generated files
+- `-q, --quiet` - Suppress output (default: false)
+
 **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.
 
 ### 3.3 Supported Target Platforms
@@ -76,6 +93,7 @@ In addition to the standard libraries provided by Beckhoff, the following librar
 - `Tc3_DALI`: Please note that this library integration is not fully tested.
 
 ## 4 Future Work
+
 - Add support for more target platforms (e.g., Siemens, Codesys)
 - Add and test support for more bus systems (e.g., EtherCAT, Profinet)
 - Add a more sophisticated module system (e.g., support multiple files, packages, imports, etc.)
@@ -86,4 +104,4 @@ In addition to the standard libraries provided by Beckhoff, the following librar
 - Support UseStmt within FB logic
 - Look into debugging DSLs
 - Look into moving the framework to a web-based solution (both the DSL and the deployment tool)
-- Look into graphical modeling
+- Look into graphical modeling