Using the Terminal Editor#

The catio-terminals GUI editor allows you to create and edit terminal description YAML files used in the fastcs-catio project.

Features#

  • File Management: Open existing YAML files or create new ones

  • Tree View: Navigate terminal types and their symbols in an intuitive tree structure

  • Terminal Management:

    • Add new terminal types by searching Beckhoff’s catalog

    • Delete existing terminal types

    • Edit terminal properties and symbol definitions

  • Beckhoff Integration:

    • Search for Beckhoff terminal types

    • Automatically populate terminal information from XML descriptions

  • Live Editing: Edit symbol properties with immediate feedback

Installation#

Install the package with the terminals extra:

uv pip install -e ".[terminals]"

Or install the required dependencies separately:

uv pip install nicegui pydantic pyyaml httpx

Launching the Editor#

Launch the terminal editor:

# Open GUI without a file (choose Open or Create New at startup)
catio-terminals edit

# Open GUI with a specific file
catio-terminals edit path/to/terminals.yaml

Or run as a Python module:

python -m catio_terminals

Getting Started#

  1. At Startup: Choose to open an existing YAML file or create a new one

  2. Tree View: Browse terminal types in the left panel

  3. Details Panel: Click on a terminal or symbol to view/edit details in the right panel

  4. Add Terminal: Click “Add Terminal” to search Beckhoff’s catalog or create manually

  5. Save: Click “Save” to write changes back to the YAML file

Main Interface#

The editor has three main sections:

  1. Header: Contains Save and Add Terminal buttons

  2. Left Panel: Tree view of terminal types and their symbols

  3. Right Panel: Details and editing interface for selected items

Adding a Terminal#

  1. Click “Add Terminal” button in the header

  2. The dialog shows a list of available terminals with search and filtering:

    Filtering by Type

    • Use the “Filter by Type” dropdown to narrow results by terminal category (Digital Input, Analog Output, etc.)

    • The filter automatically selects the category of your currently selected terminal

    Searching

    • Type in the search box to filter terminals - results update automatically as you type

    • Press Enter or just continue typing to refine the search

    • The status line shows total matches, already-added count, and available count

    Adding Terminals

    • Click “Add” on any available terminal to add it to your configuration

    • Already-added terminals appear grayed out

    • Use “Add All” to add all currently visible available terminals at once

    • Click “Close” when finished

Editing Terminal Details#

  1. Select a Terminal in the tree view

  2. View terminal information in the right panel:

    • Description

    • Identity (Vendor ID, Product Code, Revision)

    • List of symbols

  3. Click “Delete Terminal” to remove it

Editing Symbol Details#

  1. Expand a terminal in the tree view

  2. Click on a symbol to edit it

  3. Modify the fields:

    • Name Template: Pattern for symbol names (use {channel} for channel number)

    • FastCS Name: The PascalCase attribute name for FastCS (use {channel} for multi-channel)

    • Index Group: ADS index group (hex format)

    • Size: Data size in bytes

    • ADS Type: ADS data type code

    • Channels: Number of channels for this symbol

    • Type Name: The type name string

    • Access: Read-only, write-only, or read-write

    • Tooltip: Description for the symbol

  4. Changes are saved automatically in memory

YAML File Structure#

Terminal YAML files follow this structure:

terminal_types:
  EL4004:
    description: "4-channel Analog Output 0..10V 12-bit"
    identity:
      vendor_id: 2
      product_code: 0x0FA43052
      revision_number: 0x00100000
    symbol_nodes:
      - name_template: "AO Output Channel {channel}"
        fastcs_name: "AoOutputChannel{channel}"
        index_group: 0xF030
        size: 2
        ads_type: 65
        type_name: "AO Output Channel 1_TYPE"
        channels: 4
        access: "read-write"
        tooltip: "Analog output channel value"
        selected: true
      - name_template: "WcState^WcState"
        fastcs_name: "WcState"
        index_group: 0xF021
        size: 0
        ads_type: 33
        type_name: "BIT"
        channels: 1
        access: "read-only"
        selected: true

Tips#

  • Use meaningful Terminal IDs: Follow Beckhoff naming conventions (e.g., EL4004, EL2008)

  • Channels: Set the channels field to generate multiple instances of a symbol

  • Hex Values: Index groups are displayed and entered in hexadecimal (0xF030)

  • Name Templates: Use {channel} placeholder for channel-based naming in both name_template and fastcs_name

  • FastCS Names: Use PascalCase for FastCS attribute names (e.g., AoOutputChannel{channel})

  • Selection: The selected field controls which symbols are included in dynamic controllers

  • Auto-save: The app doesn’t auto-save; remember to click Save before closing

Saving Your Work#

  1. Click “Save” in the header

  2. The file is written to disk in YAML format

  3. A notification confirms the save

Integration with fastcs-catio#

The YAML files created by this tool are designed to work with the fastcs-catio project. Place them in:

src/catio_terminals/terminals/

These files are automatically loaded by the dynamic controller system to generate FastCS controllers at runtime.

Architecture#

The catio_terminals package consists of several modules:

  • models.py: Pydantic data models for YAML structure

  • beckhoff.py: Client for fetching Beckhoff terminal information

  • xml/: Subpackage for Beckhoff ESI XML parsing

    • cache.py: Caching system for downloaded XML files

    • parser.py: Main XML parsing utilities

    • pdo.py: PDO entry parsing

    • pdo_groups.py: PDO group (AlternativeSmMapping) parsing

    • coe.py: CoE object parsing

    • catalog.py: Terminal catalog browsing

  • ui_app.py: Main NiceGUI application

  • ui_components/: UI component modules (tree view, details panes)

  • ui_dialogs/: Dialog modules (file, terminal, confirmation dialogs)

  • service_*.py: Service layer modules (file, config, terminal operations)

  • main.py: Entry point for the application

Troubleshooting#

File Not Loading#

  • Ensure the YAML file is valid YAML format

  • Check file permissions

  • View error message in notification

Terminal Not Saving#

  • Ensure file path is writable

  • Check disk space

  • View error in notification

Beckhoff Terminal Search Not Working#

  • Run catio-terminals update-cache to download and cache Beckhoff XML files

  • Check internet connectivity during cache update

  • View cache status in ~/.cache/catio_terminals/

  • If the terminal list is empty, the cache needs to be updated