跳到主要内容

OpenPLC Editor 使用教程

OpenPLC 由 PC 端的 OpenPLC Editor 和设备端的 OpenPLC Runtime 组成。OpenPLC Editor 用于创建、编译和上传 IEC 61131-3 程序,OpenPLC Runtime 负责在 Luckfox Lyra PLC 上运行程序并访问硬件。

本教程以梯形图(Ladder Diagram,LD)控制板载继电器 0 为例,依次介绍软件安装、输出映射配置、项目创建和程序上传。

1. 安装 OpenPLC Editor(PC 端)​

  1. 打开 OpenPLC 下载页面,根据 PC 的操作系统选择对应版本的 OpenPLC Editor 并下载安装包。
  2. 下载完成后,运行安装程序,根据安装向导的提示完成 OpenPLC Editor 的安装。
  3. 安装完成后,启动 OpenPLC Editor,进入主界面即可开始创建或编辑 PLC 工程。

2. 安装 OpenPLC Runtime(Lyra PLC 端)​

Luckfox Lyra PLC 运行 Debian 12,可按 Linux 方式安装 OpenPLC Runtime。

  1. 通过 SSH 登录 Luckfox Lyra PLC。

  2. 获取 OpenPLC Runtime 源码并运行安装脚本:

    git clone https://github.com/Autonomy-Logic/openplc-runtime.git
    cd openplc-runtime
    sudo ./install.sh
  3. 确认服务正在运行:

    sudo systemctl status openplc-runtime.service

常用服务管理命令如下:

sudo systemctl start openplc-runtime.service
sudo systemctl stop openplc-runtime.service
sudo systemctl restart openplc-runtime.service

3. 配置 OpenPLC Runtime 输出映射​

3.1 OpenPLC 地址格式​

%QX0.0 是 PLC 输出区第 0 字节的第 0 位,按 IEC 61131-3 直接地址格式定义。各部分含义如下:

地址部分含义
%直接地址标识
Q输出区
X位类型,对应 BOOL
0(小数点前)字节索引,从 0 开始
0(小数点后)位索引,从 0 开始

本教程将第一路继电器 Relay0 分配到 %QX0.0,第二路继电器 Relay1 分配到 %QX0.1。这两个地址由 PLC 程序指定,并不是从 GPIO 编号换算而来。

3.2 板载继电器映射​

%QX0.0 是 PLC 逻辑地址,GPIO17 是 Linux GPIO 编号,二者需要通过 Runtime 硬件插件关联。本教程在插件中配置以下映射:

OpenPLC 输出Linux GPIORK3506 管脚外壳标识
%QX0.0GPIO17GPIO0_C1 / RMIO_17RELAY0
%QX0.1GPIO18GPIO0_C2 / RMIO_18RELAY1

板载继电器共 2 路,RELAY0 和 RELAY1 可独立控制。每路包含常开(NO)× 1、常闭(NC)× 1,共用公共端(COM)。两路控制输入均为高电平有效,状态关系如下:

控制输入继电器线圈COM 与 NOCOM 与 NC
低电平(GPIO 输出 0)不吸合,继电器释放断开导通
高阻或悬空,由下拉电阻保持低电平不吸合,继电器释放断开导通
高电平(GPIO 输出 1)吸合导通断开

“高电平有效”描述的是继电器控制输入,不是触点输出电压。NO、NC 和 COM 是无源机械开关触点,本身不会主动输出电压。接线时请以设备端子标识为准。

以 Relay0 为例,程序输出到继电器动作的过程如下:

3.3 添加 Lyra GPIO 插件​

OpenPLC Runtime v4 使用插件访问硬件。以下插件读取 %QX0.0 和 %QX0.1 对应的输出缓冲区,并将状态写入 GPIO17 和 GPIO18。

两路继电器控制输入均设有下拉电阻。上电初始化期间,GPIO 处于高阻或悬空状态时,下拉电阻使线圈保持不吸合。插件随后向 GPIO 的 direction 文件写入 low,将 GPIO 配置为低电平输出,继续保持继电器释放;输出高电平时线圈吸合,无需反转控制逻辑。下拉电阻可避免输入悬空引起的误吸合,但不能抵消软件主动输出的高电平。

  1. 进入 OpenPLC Runtime 目录并创建插件目录:

    cd ~/openplc-runtime
    sudo mkdir -p core/src/drivers/plugins/python/lyra_gpio
    sudo nano core/src/drivers/plugins/python/lyra_gpio/lyra_gpio.py
  2. 将以下代码写入 lyra_gpio.py 并保存:

    lyra_gpio.py 完整代码
    #!/usr/bin/env python3
    import errno
    import os
    import sys
    import threading
    import time

    sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))

    from shared import SafeBufferAccess, safe_extract_runtime_args_from_capsule

    # (byte index, bit index, Linux GPIO)
    RELAY_MAP = ((0, 0, 17), (0, 1, 18))
    GPIO_ROOT = "/sys/class/gpio"

    _buffer = None
    _worker = None
    _stop_event = threading.Event()


    def _write_text(path, value):
    with open(path, "w", encoding="ascii") as stream:
    stream.write(value)


    def _prepare_gpio(pin):
    gpio_dir = os.path.join(GPIO_ROOT, f"gpio{pin}")
    if not os.path.isdir(gpio_dir):
    try:
    _write_text(os.path.join(GPIO_ROOT, "export"), str(pin))
    except OSError as exc:
    if exc.errno != errno.EBUSY:
    raise

    for _ in range(50):
    if os.path.isdir(gpio_dir):
    break
    time.sleep(0.01)

    if not os.path.isdir(gpio_dir):
    raise RuntimeError(f"GPIO{pin} was not exported")

    # Active-high control: initialize low to keep the coil de-energized.
    _write_text(os.path.join(gpio_dir, "direction"), "low")


    def _set_gpio(pin, enabled):
    value_path = os.path.join(GPIO_ROOT, f"gpio{pin}", "value")
    _write_text(value_path, "1" if enabled else "0")


    def init(runtime_args_capsule):
    global _buffer

    runtime_args, error = safe_extract_runtime_args_from_capsule(
    runtime_args_capsule
    )
    if runtime_args is None:
    print(f"[lyra_gpio] Failed to access Runtime buffers: {error}")
    return False

    _buffer = SafeBufferAccess(runtime_args)
    if not _buffer.is_valid:
    print(f"[lyra_gpio] Invalid Runtime buffer: {_buffer.error_msg}")
    return False

    try:
    for _, _, pin in RELAY_MAP:
    _prepare_gpio(pin)
    except Exception as exc:
    print(f"[lyra_gpio] GPIO initialization failed: {exc}")
    return False

    return True


    def _run():
    previous = {}
    while not _stop_event.wait(0.02):
    for byte_index, bit_index, pin in RELAY_MAP:
    value, error = _buffer.read_bool_output(byte_index, bit_index)
    if error != "Success":
    continue

    enabled = bool(value)
    if previous.get(pin) != enabled:
    _set_gpio(pin, enabled)
    previous[pin] = enabled


    def start_loop():
    global _worker
    _stop_event.clear()
    _worker = threading.Thread(target=_run, daemon=True)
    _worker.start()
    return 0


    def stop_loop():
    global _worker
    _stop_event.set()
    if _worker is not None:
    _worker.join(timeout=1)
    _worker = None

    for _, _, pin in RELAY_MAP:
    try:
    _set_gpio(pin, False)
    except OSError:
    pass


    def cleanup():
    stop_loop()
  3. 编辑 Runtime 根目录中的 plugins.conf:

    sudo nano plugins.conf
  4. 在文件末尾添加以下配置。字段依次表示插件名称、路径、启用状态和插件类型,其中 0 表示 Python 插件。

    lyra_gpio,./core/src/drivers/plugins/python/lyra_gpio/lyra_gpio.py,1,0
  5. 重启 Runtime 并检查日志:

    sudo systemctl restart openplc-runtime.service
    sudo journalctl -u openplc-runtime.service -n 100 --no-pager
GPIO 控制权

Luckfox Lyra PLC WebUI 也可以控制 GPIO17 和 GPIO18。OpenPLC Runtime 运行期间,不要同时通过 WebUI 操作继电器,否则两个程序可能写入不同状态。

4. 编写并上传梯形图程序​

4.1 创建项目​

  1. 启动 OpenPLC Editor,点击 "New Project"。

  2. 选择 "PLC Project",然后点击 "Next"。

  3. 输入项目名称,选择一个空目录作为项目路径,然后点击 "Next"。

  4. 在基础程序语言中选择 "Ladder Diagram",然后创建项目。

4.2 编写继电器控制程序​

本例使用一个初始值为 TRUE 的常开触点驱动 Relay0 线圈,程序运行后使板载继电器 0 吸合。

继电器接线安全

首次运行时不要在继电器触点上连接市电或大功率负载。继电器端子提供无源触点,不是 3.3 V GPIO 接口。可通过动作声确认继电器动作,或用万用表通断档检查未接负载的触点状态。

  1. 创建以下变量:

    NameClassTypeLocationInitial Value
    AlwaysOnLocalBOOL-TRUE
    Relay0OutputBOOL%QX0.0FALSE
  2. 在梯形图中添加一个 AlwaysOn 常开触点和一个 Relay0 线圈:

    |----[ AlwaysOn ]----------------( Relay0 )----|
  3. 确认 Relay0 的 Location 为 %QX0.0。生成的结构化文本(Structured Text,ST)应包含类似声明:

    Relay0 AT %QX0.0 : BOOL;

4.3 连接 Luckfox Lyra PLC​

  1. 在项目树中打开 "Device" > "Configuration"。

  2. 在 "IP Address" 中输入 Luckfox Lyra PLC 的实际 IP 地址,然后点击 "Connect"。

  3. 输入 OpenPLC Runtime 的登录信息。

    Runtime 登录账户

    OpenPLC Runtime 的默认账户和密码均为 root。该账户与 Debian 的 SSH 登录账户不是同一组凭据。如果已经修改 Runtime 密码,请使用修改后的密码。

  4. 控制台显示 "connected" 和 "PLC RUNNING" 后,表示连接成功。

4.4 编译并上传程序​

  1. 点击左侧工具栏中的编译图标。

  2. 点击 "Build and Upload"。

  3. 等待控制台报告编译、上传和启动成功。

  4. 程序开始运行后,板载继电器 0 应吸合一次。通过动作声或万用表确认触点状态。

测试完成后停止 PLC,或将 AlwaysOn 的初始值改为 FALSE 后重新上传,使继电器释放。