引言：开启您的 ctrlX 自动化之旅

欢迎来到 ctrlX AUTOMATION 的世界！如果您是一位有软件开发背景，但对工业自动化领域感到陌生的开发者，那么这篇教程正是为您量身定制的。

首先，让我们明确一下 ctrlX OS 是什么。它是由博世力士乐专为工业控制设备打造的自动化操作系统。与您可能熟悉的 Web 或移动应用开发不同，ctrlX OS 的开发环境有其独特性。在这里，我们强调的是实时性（设备必须在毫秒级内响应）、可靠性（代码必须极其稳定以控制物理设备），以及特定的打包格式（所有应用都必须打包为 Snap 格式才能在控制器上运行）。这些要求意味着，为 ctrlX OS 开发应用，需要遵循一套严谨的流程和规范。

本教程的目标非常明确：我们将引导一位毫无 ctrlX App 开发经验的开发者，从零开始，一步步完成从搭建开发环境到成功部署第一个示例应用的完整流程。

通过本教程，您将掌握以下核心技能：

• 环境搭建：在 Windows 主机上安装并配置核心开发套件 ctrlX WORKS。
• 虚拟机管理：创建、配置并连接到用于编译应用的 Linux 构建环境。
• SDK 安装：在构建环境中部署 ctrlX AUTOMATION SDK。
• 构建与部署：基于官方 C++ 示例，构建一个 .snap 应用包，并将其部署到虚拟控制器 ctrlX COREvirtual 上。
• 功能验证：通过 ctrlX 的核心组件“数据层 (Data Layer)”来验证您的应用是否已成功运行。

准备好了吗？让我们开始这段激动人心的自动化开发之旅。

1. 准备您的开发主机 (Windows)

在正式编写代码之前，我们需要在您的 Windows 电脑上搭建一个功能完备的开发环境。本章节将详细介绍其独特的开发架构、系统要求以及核心工具 ctrlX WORKS 的安装步骤。

1.1. 核心开发理念解析：Windows 主机与 Linux 构建环境

ctrlX WORKS 本质上是一个强大的“工程工具箱”，其核心开发架构是一个巧妙的设计：您的开发工作始于熟悉的 Windows 主机，但应用的实际构建、编译和打包却是在一个由 ctrlX WORKS 自动创建和管理的 Linux 虚拟机（我们称之为 App 构建环境）中完成的。

这种“宿主在 Windows，构建在 Linux”的分离式架构是经过深思熟虑的战略选择，它带来了诸多优势：

• 一致性与可复现性：确保每一位开发者的应用都在一个标准、统一的 Linux 环境中构建，避免了因本地环境差异导致的“在我电脑上能运行”的问题。
• 开发者体验：允许您继续使用自己偏爱的 Windows 开发工具（如 Visual Studio Code）和工作流程，无需完全切换到 Linux 桌面环境。
• 无缝集成：ctrlX WORKS 完美地管理着两者之间的交互，使得这个过程对开发者来说尽可能平滑。

为了帮助您更清晰地理解这一概念，下表对比了两者各自扮演的角色：

环境	扮演的角色	主要活动
Windows 主机	开发与管理中心 (Development & Management Hub)	安装 ctrlX WORKS，使用图形界面管理虚拟机，连接 IDE（如 VS Code），与虚拟控制器交互。
Linux 构建环境	编译与打包工厂 (Compilation & Packaging Factory)	安装 ctrlX AUTOMATION SDK，执行编译脚本，最终生成 .snap 格式的应用包。

理解了这一核心理念后，我们来看看您的 Windows 主机需要满足哪些具体要求。

1.2. 系统要求与必备软件

为了确保 ctrlX WORKS 能够顺畅运行，请确保您的 Windows 主机满足以下硬件和软件要求。

要求类别	最低配置	推荐配置/说明
操作系统	Windows 10/11 (64位) 专业版或更高版本	–
内存 (RAM)	8 GB	16 GB 或更多，尤其是在同时运行 App 构建环境和虚拟控制器时。
可用磁盘空间	20 GB	20 GB 或更多，用于存储 ctrlX WORKS、虚拟机镜像及项目文件。
软件依赖	.NET Framework 4.8	.NET Framework 4.8 或更高版本。

提示：虽然官方原生不支持在 Linux 或 macOS 上安装 ctrlX WORKS，但技术上您可以通过虚拟机（例如，在 macOS 上使用 VMware 或 Hyper-V 运行一个 Windows 虚拟机）来间接使用。然而，为了获得最佳的性能和最无缝的集成体验，我们强烈建议直接在 Windows 操作系统上运行。

满足以上要求后，您就可以着手下载并安装 ctrlX WORKS 了。

1.3. 下载并安装 ctrlX WORKS

请遵循以下步骤完成 ctrlX WORKS 的下载和安装。

1. 第一步：注册 Bosch ID ctrlX WORKS 虽然免费，但下载前需要一个 Bosch ID。如果您还没有，请访问 boschrexroth.com 网站完成注册。这是访问博世力士乐众多开发资源的通行证。
2. 第二步：访问官方下载页面 使用您的 Bosch ID 登录后，请访问以下官方开发者社区页面：
   • 下载链接：https://developer.community.boschrexroth.com/t5/Store-and-How-to/ctrlX-WORKS/ba-p/16448 在该页面上，找到并点击 “Download ctrlX WORKS now” 按钮，下载最新版本的安装程序。
3. 第三步：执行安装 您将下载一个约 500MB 的 .exe 安装包。安装过程非常简单，只需双击运行并遵循向导提示即可。
4. 第四步：首次启动与配置 安装完成后，首次启动 ctrlX WORKS 时请保持耐心。系统需要大约 10-15 分钟来自动下载、配置其内部的 Linux 构建环境。这是一个一次性的设置过程，请确保网络连接稳定。在此期间，安装程序还会引导您下载用于后续测试的虚拟控制器——ctrlX COREvirtual。

完成这些步骤后，ctrlX WORKS 就已成功安装在您的主机上。接下来，我们将创建第一个具体的 App 构建环境。

2. 创建并配置您的 App 构建环境

现在，ctrlX WORKS 已经就位，是时候创建我们专用的 Linux 虚拟机了。这个“App 构建环境”是您所有 ctrlX App 的诞生地，它负责编译源代码并将其打包成标准格式。

2.1. 在 ctrlX WORKS 中创建虚拟机

App 构建环境的本质是一个由 ctrlX WORKS 在后台管理和运行的 QEMU 虚拟机。它为我们提供了一个隔离且标准化的 Ubuntu Server 环境，是应用编译和打包的中心。

请按照以下步骤创建一个新的 App 构建环境：

1. 导航至 App 构建环境视图 在 ctrlX WORKS 的左侧边栏中，点击并选择 “App Build Environments”。
2. 添加新环境 在视图的右上角，点击 + (加号) 图标，这将打开 “Add ctrlX CORE App Build Environment” 对话框。
3. 配置环境参数 在对话框中，您需要配置几个关键参数：
   • Name：为您的环境起一个有意义的名称，例如 my-first-dev-env。
   • Storage location：选择一个磁盘空间充足的位置来存放虚拟机文件。
   • Port forwarding：这是连接主机和虚拟机的关键。默认设置 10022:22 意味着您 Windows 主机的 10022 端口将被转发到虚拟机的 22 端口（SSH 服务）。请保持此默认设置，它将使我们能够通过 SSH 轻松连接到虚拟机。
4. 配置网络代理（如需） 如果您的开发主机位于公司代理服务器之后（即无法直接访问互联网），必须勾选 “Use HTTP and HTTPS proxy on localhost:3128” 选项。
5. 完成创建 点击 “OK” 按钮。ctrlX WORKS 将开始创建环境。请记住，新环境的默认用户账户和密码均为 boschrexroth。

创建完成后，我们就可以启动并连接到这个全新的虚拟机了。

2.2. 启动并连接到虚拟机

启动虚拟机分为两个阶段：首次初始化和常规启动。理解它们的区别非常重要。

1. 首次启动与初始化 在 App 构建环境列表中，找到您刚刚创建的环境，点击其右侧的“播放” (▶️) 图标。第一次启动时，ctrlX WORKS 会自动从网络下载 Ubuntu 服务器的镜像文件，并在虚拟机中进行安装和基础配置。这个过程需要一些时间，完成后，虚拟机会自动关闭。这是完全正常的行为。
2. 重新启动 当虚拟机状态显示为已停止后，再次点击“播放” (▶️) 图标。这一次是常规启动，虚拟机会正常进入运行状态。稍等片刻，您会看到其状态变为绿色的 “Online”。
3. 通过 SSH 连接 当虚拟机在线后，点击对应条目中的 SSH 链接 (ssh://boschrexroth@localhost:10022)。ctrlX WORKS 会为您打开一个终端会话。系统会提示您输入密码，请输入 boschrexroth 并按回车。成功登录后，您会看到虚拟机的命令行提示符，这表明您已成功连接。

现在我们已经身处 Linux 构建环境之中，只差最后一步就可以开始构建应用了——安装核心开发工具包。

2.3. 在虚拟机中安装 ctrlX AUTOMATION SDK

ctrlX AUTOMATION SDK 是我们开发工作的基石。它包含了编译 ctrlX App 所需的所有头文件、库、实用工具以及丰富的示例代码。在虚拟机内部安装 SDK 是进行任何开发工作前的强制性步骤。

你可以在Windows下下载ctrlX AUTOMATION SDK，并通过VS Code拷贝到远程服务器中。另外，你也可以在终端运行此脚本以下载并安装最新的 ctrlX AUTOMATION SDK。在您刚刚打开的 SSH 终端中，执行以下命令：

wget https://raw.githubusercontent.com/boschrexroth/ctrlx-automation-sdk/main/scripts/clone-install-sdk.sh && chmod a+x *.sh && ./clone-install-sdk.sh

这个预置的脚本会自动从 GitHub 下载最新版本的 SDK 并完成所有安装步骤。

为了开发 ctrlX CORE 应用程序还需要配置一套特殊的软件包和设置，以确保 App 能够符合 ctrlX AUTOMATION 平台的规范。

需要在用户远程登录到虚拟机中，在用户目录分别执行下面一些命令

ctrlx-automation-sdk/scripts/install-required-packages.sh
ctrlx-automation-sdk/scripts/install-snapcraft.sh
ctrlx-automation-sdk/scripts/install-ctrlx-datalayer.sh 

这些脚本的作用如下：

1. 安装基础依赖： 运行第一个脚本（install-required-packages.sh）旨在部署构建应用程序所需的基础 Linux 系统依赖和软件包。
2. 集成打包工具： 安装 Snapcraft （install-snapcraft.sh）是必不可少的步骤，因为所有 ctrlX 应用程序都必须打包成特定的 Snap 文件格式，才能在 ctrlX CORE 设备上运行。
3. 获取核心机制接口： 安装 ctrlx-datalayer Debian 软件包（install-ctrlx-datalayer.sh）目的在于提供与系统核心机制 ctrlX Data Layer（数据层） 交互所需的库和工具，这是应用程序间通信的基础。

完成这些重要的安装脚本 后，开发环境便具备了构建 C++ 和 Python 示例项目的能力。

至此，一个功能完整的 ctrlX App 开发环境已经准备就绪！我们已经为构建第一个应用铺平了所有道路。

3. 构建、部署与测试您的第一个 App

万事俱备，现在是时候进入最激动人心的部分了。我们将从一个官方示例项目开始，完整体验构建、部署和验证一个真实 ctrlX App 的全过程。

在完成 SDK 的核心安装并确保 C++和基础 Python 示例项目可构建之后，若开发者希望使用其他编程语言（如 Go、.NET 或 Node.js）来构建应用程序，则需要进一步的安装配置步骤。这些在 ctrlx-automation-sdk/scripts 目录额外的安装脚本是为特定的编程语言准备的，旨在构建和测试对应的示例项目。

SDK 为每种主流语言都提供了专用脚本，例如用于安装 Go 语言环境的脚本 (install-go.sh)、用于安装 Microsoft .NET 运行时环境的脚本 (install-dotnet-sdk.sh)，以及用于配置 Node.js 和 npm 的脚本 (install-nodejs-npm.sh)。通过运行这些位于 ctrlx-automation-sdk/scripts 目录下的脚本，开发环境将自动下载所需的语言工具链和依赖，从而提供完整的开发能力。此外，针对 Python 项目，还有特定的脚本用于创建和激活独立的 Python 虚拟环境（venv），确保项目依赖项的隔离和准确安装。简而言之，这些脚本是扩展 App 构建环境，以支持多语言开发的关键辅助工具。

3.1. 从示例项目开始：构建 Snap 包

直接从一个功能完备的官方示例项目入手，是一个绝佳的学习策略。它能让我们暂时不必关心代码细节，而是专注于理解 ctrlX AUTOMATION 的构建和部署流程。

本教程将使用 datalayer.register.node 这个 C++ 示例项目。选择它的原因在于，它能清晰地展示一个 App 如何与 ctrlX 的核心组件——数据层 (Data Layer)——进行交互。

请在您的 SSH 终端中，按照以下步骤完成构建：

1. 进入项目目录 首先，使用 cd 命令导航到示例项目的文件夹。
2. 执行构建脚本 每个示例项目都包含用于不同目标平台的构建脚本。由于我们将在 ctrlX CORE virtual（一个基于 amd64 架构的虚拟控制器）上进行测试，因此我们应使用对应的构建脚本 build-snap-amd64.sh 来生成当前虚拟机上使用的snap包。
3. 理解构建产物 构建过程成功结束后，您会在当前目录下发现一个新生成的文件，其后缀为 .snap。Snap 是 ctrlX App 官方指定的、唯一的打包和分发格式。

现在，我们已经成功构建了应用包，下一步需要将它从 Linux 虚拟机中取回到 Windows 主机。

3.2. 将 Snap 包传回 Windows 主机

为什么需要这一步？因为我们将通过 Windows 主机上的浏览器来访问虚拟控制器的网页管理界面，并通过该界面上传并安装我们的应用。

如果使用VS Code，可以直接在对应文件夹下载项目目录下的 “xxx.amd64.snap”文件夹。

如果使用终端来操作，请打开一个新的 Windows 命令行工具 (cmd.exe 或 PowerShell)，而不是在之前的 SSH 终端中，然后执行下面的 scp (Secure Copy) 命令来完成文件传输。

# 请在 Windows 主机的命令行中运行此命令
scp -P 10022 boschrexroth@localhost:~/ctrlX-automation-sdk/samples-cpp/datalayer.register.node/*.snap .

让我们分解一下这个命令的含义：

• -P 10022：指定连接的端口，这正是我们在创建虚拟机时设置的 SSH 转发端口。注意：scp 命令使用大写的 -P 来指定端口，这与其他一些工具（如 ssh）可能不同。
• boschrexroth@localhost：指定了虚拟机的登录用户名和地址。
• : 之后的部分：这是源文件的路径，即虚拟机中 .snap 文件的位置。
• . (点)：表示当前目录，即我们希望将文件复制到的目标位置（您的 Windows 主机当前命令行所在的文件夹）。

当提示输入密码时，输入 boschrexroth。命令执行完毕后，.snap 文件就会出现在您的 Windows 文件夹中，为部署做好了准备。

3.3. 部署并验证 App

这是见证奇迹的时刻！我们将把构建好的应用安装到虚拟控制器上，并验证它是否按预期工作。

1. 启动 ctrlX COREvirtual 回到 ctrlX WORKS，在虚拟控制器列表中找到 ctrlX COREvirtual 实例，并点击“播放” (▶️) 图标启动它。
2. 访问 Web 界面 当虚拟控制器状态变为 “Online” 后，通过浏览器访问其管理界面（通常地址为 https://localhost:8443 或 https://192.168.1.1，具体取决于您的网络配置）。使用默认凭据（用户名 admin，密码 boschrexroth）登录。
3. 安装 App
   • 首先，我们需要允许安装来自未知来源的应用。导航到 Settings (设置)，找到并点击 Apps。在打开的页面中，点击右上角的齿轮图标进入设置，勾选 “Allow installation from unknown source” (允许安装来自未知来源的应用) 选项。
   • 返回 Apps 主页面，点击 “Install from file” (从文件安装) 按钮。
   • 在弹出的文件选择对话框中，找到并选择我们刚刚从虚拟机传回的 .snap 文件。上传并完成安装。
4. 验证功能 这是最关键的验证环节。安装成功后，应用会自动运行。
   • 导航到 Settings -> ctrlX Data Layer。
   • 在左侧的数据层树状结构中，您应该能看到一个名为 sdk-cpp-registernode/ 的新根节点。
   • 展开这个节点，您会看到其下包含了由我们刚刚安装的 App 动态创建的多个子节点。
5. 如果您能看到这些节点，那么恭喜您！ 这证明您的第一个 ctrlX App 已经成功运行，并与系统的数据层进行了正确的交互。

4. 总结与后续步骤

4.1. 回顾您已完成的成就

让我们花点时间回顾一下您在本教程中取得的丰硕成果。通过亲手实践，您已经完成了一个完整的端到端开发流程，并掌握了以下关键技能：

• 成功安装并配置了核心开发工具 ctrlX WORKS。
• 创建、启动并连接到了一个基于 Linux 的 App 构建环境。
• 在构建环境中安装了 ctrlX AUTOMATION SDK。
• 基于官方示例项目，成功构建了一个 .snap 格式的应用程序包。
• 将应用部署到了 ctrlX COREvirtual 虚拟控制器上。
• 通过 ctrlX Data Layer 验证了应用的成功运行。

这些都是成为一名合格的 ctrlX App 开发者所必须经历的步骤。您已经为更深入的探索打下了坚实的基础。

4.2. 探索更广阔的 ctrlX 世界

成功部署第一个应用只是一个开始。ctrlX AUTOMATION 是一个强大而开放的平台，现在您可以朝着以下方向继续深入探索：

• 探索更多示例 ctrlX AUTOMATION SDK 中包含了针对多种编程语言（如 C++, Python, .NET, Go, Node.js）和不同功能的大量示例项目。浏览这些示例是学习新技能的最佳途径。
• 学习调试技巧 开发过程中不可避免地会遇到问题。ctrlX 平台提供了分层级的调试方法，我们建议您按以下顺序尝试：
  1. Snap 日志 (最简单)：这是排查问题的第一道防线，也是最简单的方法。您可以通过 Web 界面中的诊断日志或命令行查看应用的实时输出。
  2. 在构建环境中调试 (推荐)：这是我们推荐的主要应用逻辑测试方法。直接在您的 Linux 虚拟机中运行和调试代码，可以避免部署到目标设备带来的额外复杂性。
  3. 远程调试 (高难度)：这是一种功能强大但配置复杂（官方文档称之为 “Very very high effort”）的终极手段。仅当应用在真实硬件上的行为与在构建环境中不一致时，才考虑使用此方法。 建议您查阅 SDK 中的 Debugging Overview 文档以获取每种方法的详细信息。
• 深入核心概念 为了开发出更强大、更专业的应用，我们鼓励您深入阅读官方文档，以全面理解平台的核心概念，例如：
  • ctrlX Data Layer 的提供者/消费者模型。
  • 应用的生命周期管理与身份管理 (Identity Management)。
  • 备份与恢复机制 (Persisting Configurations)。
  • 许可集成 (License Management) 机制。
  • ctrlX 日志簿与诊断系统 (Logbook/Diagnostics system)。

恭喜您成功迈出了成为 ctrlX App 开发者的第一步！祝您在自动化的世界里探索愉快，创造无限可能。