From 0585de6ea4b3449956fbb352f60c8bf2c063ed2c Mon Sep 17 00:00:00 2001 From: Elias Date: Tue, 3 Feb 2026 23:32:48 +0100 Subject: [PATCH 1/2] docs: update prerequisites and enhance CLI usage instructions --- README.md | 2 +- TcAutomation/README.md | 35 +++++++++++++++++++++++++++++++++++ language/README.md | 26 ++++++++++++++++++++++---- 3 files changed, 58 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index bcaf5cb..1a9641d 100644 --- a/README.md +++ b/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 diff --git a/TcAutomation/README.md b/TcAutomation/README.md index 82de767..707ac23 100644 --- a/TcAutomation/README.md +++ b/TcAutomation/README.md @@ -15,3 +15,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 +``` + +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" +``` diff --git a/language/README.md b/language/README.md index fec07b1..382a4e7 100644 --- a/language/README.md +++ b/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 +bcs-engineering-cli beckhoff generate [options] ``` +**Options:** + +- `-d, --destination ` - Output directory for generated files +- `-q, --quiet` - Suppress output (default: false) + ### 3.2 Generate Code and Deploy ```bash -bcs-engineering-cli beckhoff deploy +bcs-engineering-cli beckhoff deploy [options] ``` +**Options:** + +- `--template-path ` - TwinCAT template path +- `--solution-name ` - Solution name (default: `MyGeneratedSolution`) +- `--project-name ` - Project name (default: `MyTwinCATProject`) +- `--plc-name ` - PLC project name (default: `MyPlcProject`) +- `--tc-exe ` - Path to TcAutomation executable (default: `TcAutomation.exe`, resolved from PATH) +- `--ads-username ` - ADS username for remote connection (default: `Administrator`) +- `--ads-password ` - ADS password for remote connection (default: `1`) +- `-d, --destination ` - 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 \ No newline at end of file +- Look into graphical modeling From 9cf6c357d852c06ccea557275caa874c53ce241f Mon Sep 17 00:00:00 2001 From: Elias Date: Tue, 3 Feb 2026 23:50:03 +0100 Subject: [PATCH 2/2] docs: add TwinCAT setup guide and prerequisites --- TcAutomation/README.md | 1 + TcAutomation/TWINCAT_SETUP.md | 118 ++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 TcAutomation/TWINCAT_SETUP.md diff --git a/TcAutomation/README.md b/TcAutomation/README.md index 707ac23..bf6f6be 100644 --- a/TcAutomation/README.md +++ b/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 diff --git a/TcAutomation/TWINCAT_SETUP.md b/TcAutomation/TWINCAT_SETUP.md new file mode 100644 index 0000000..550cba7 --- /dev/null +++ b/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 \ No newline at end of file