Get the current session status: Control Expert server version, whether a project is open, its file path, CPU, version and build state.

Open a Control Expert project file.

Supports .stu (native project), .sta (archive), and .xef/.zef (XML exchange format, imported into a fresh application). Any previously open project is closed without saving. Opening can take 30-120 s for large projects.

Create a new project from scratch for a given PLC CPU.

cpu_part_number must exactly match a CPU reference in the installed Control Expert hardware catalog, e.g. 'BMX P34 2020' (M340), 'BME P58 2040' (M580), 'TSX P57 4634M' (Premium), '140 CPU 651 60' (Quantum). cpu_version is the firmware version offered by the catalog and is required, e.g. '02.70'. The project exists only in memory until save_project is called with a path.

Save the open project. Pass path (ending in .stu) on first save or to save a copy under a new name; leave empty to save in place.

Close the open project, optionally saving first. Unsaved changes are discarded when save=False.

Build the project (incremental by default, full rebuild with rebuild_all=True). Returns the resulting build state and, when available, the Control Expert output window text with errors/warnings. A successful build is required before transferring to a PLC or simulator.

Read a project setting value by its identifier (e.g. 'unity.multiAssign', 'unity.nestedComment', 'unity.RemanentLink'). Idents appear as in an exported .xef.

Set one or more project settings (build/language options). Common idents: 'unity.multiAssign'='1' allows chained assignments a:=b:=c (error E1203 if disabled), 'unity.nestedComment', 'unity.paramNotAssign', 'unity.emptyParaAllowed'. Values are strings ('0'/'1' for booleans). The project is reloaded from a patched archive and UNSAVED — build_project then save_project afterwards.

Run a syntax/semantic analysis of the project without generating code. Faster than a build; use it to validate edits.

List the program structure: tasks (MAST, FAST, ...) with their scan settings and the sections in each task (name + IEC language), plus counts of events and functional modules.

List user data types in the project: DFB types (function blocks) and DDTs (structured/array types) with their versions.

List global variables with type, comment, topological address (%MW..., %I..., etc.) and initial value. name_filter does a case-insensitive substring match on the variable name.

Create a global variable.

type_name is an IEC type ('BOOL', 'EBOOL', 'INT', 'DINT', 'REAL', 'TIME', 'STRING', ...), an array ('ARRAY[0..9] OF INT'), a DDT or a DFB type name. address is an optional topological address like '%MW100' or '%Q0.2.0'.

Update attributes of an existing variable. Only the non-empty arguments are applied. To clear an attribute, pass a single space.

Delete a global variable by name.

REQUIRED READING before writing any program logic: the authoring guide for a Control Expert language ('ST', 'LD', 'FBD', 'SFC', 'IL').

Returns the exchange-XML structure rules (validated against a live Control Expert build) and a complete example section that imports and builds with 0 errors — mirror its shapes exactly. Workflow: read this guide -> write the section XML -> import_xml(kind='section') -> build_project -> fix any errors listed in the build output -> repeat. For ST, prefer the write_st_logic tool (no XML needed).

Write a program section in plain IEC 61131-3 Structured Text — no XML required. Creates the section or replaces its logic if it exists.

st_source is raw ST (IF/CASE/FOR, FB calls like 'T1(IN := x, PT := t#3s, Q => y);', set()/reset() on EBOOLs, re()/fe() edges). declare optionally declares variables as a comma-separated 'name:TYPE' list, e.g. 'StartPB:BOOL, Delay1:TON, Level:REAL' — FB instances called in the code (TON/TOF/CTU/DFB types) must exist or be declared here. Run build_project afterwards and fix any errors from its output.

Read the logic of a program section as Control Expert XML. The XML contains the source code (ST text, ladder rungs, FBD networks...) and is the same format accepted by import_xml(kind='section').

Create a new empty program section in a task.

language: ST, LD, FBD, SFC, IL or LL984. To fill it with logic, follow up with import_xml(kind='section') using XML in the shape returned by read_section.

Delete a program section from a task.

Add a task to the project. task_type: MAST, FAST, AUX0..AUX3 or SAFE. periodicity_ms > 0 makes the task periodic with that period.

Import Control Expert XML into the open project — the main way to write program logic and bulk content.

kind: 'section' (program logic, requires task), 'variables', 'dfb', 'ddt', 'configuration', or 'project' (generic project-level import of an exchange file). Provide the XML either inline via xml_content or as file_path. import_mode: 'overwrite' (default), 'keep_existing' or 'rename'.

Tip: export an existing object first (read_section / export_xml) and use its XML as the structural template — Control Expert validates the schema strictly.

Export project content as Control Expert XML and return it inline.

kind: 'variables' (all variables), 'program' (all program logic), 'configuration' (hardware config), 'dfb' (one DFB type, requires name), 'section' (one section, requires task and name). Large exports are written to a temp file and the path is returned instead.

Export the full application to a .xef or .zef XML exchange file — useful for backup, diffing, or migrating between Control Expert versions.

List the project's animation tables (watch tables used to monitor and force variable values online).

Create an animation table (or add to an existing one) and fill it with variables to watch. variables is a comma-separated list of variable names, e.g. 'Motor, StartPB, UF1_Sequence.S_Service.x, Level'. With the project online (simulator or PLC), the table shows live values in the Control Expert UI.

Delete an animation table by name.

List the full hardware configuration: CPU plus the bus → drop → rack → module tree with part numbers, versions and topological addresses.

Add a hardware module (IO, communication, ...) to a rack slot.

part_number and version must exactly match the hardware catalog for the PLC family, e.g. 'BMX DDI 1602' (16x DI), 'BMX DDO 1602' (16x DO), 'BMX AMI 0410' (4x AI), 'BMX NOE 0100' (Ethernet) — version '02.00' fits most M340 IO modules ('01.00' for some; try both). slot is the rack position (the CPU usually occupies slot 0). rack/drop/bus default to the local rack on the local bus; use get_hardware to see the topology.

Remove the module at a rack slot.

Add a drop to a bus — e.g. a remote X80 EIO drop on the EIO/RIO bus of an M580 ('M580 Drop for Ethernet'). bus is a substring of the bus name from get_hardware (e.g. 'EIO'); drop is the drop topo number. Then use add_rack and add_io_module to populate it (remote racks need their own power supply).

Add a rack to a drop (e.g. 'BME XBP 1200' in a remote EIO drop). Then add a power supply and modules with add_io_module (set drop/bus to target the remote rack; remote drops start with a CRA adapter in slot 0).

Replace a module in place (keeps the slot) — e.g. swap the default power supply new_project puts on the local rack. Old part number/version must match the current module exactly (see get_hardware).

Replace a rack in place (e.g. the default BME XBP 0800 new_project creates -> BME XBP 0400). Modules on the rack are kept where the new rack has the same slots.

Replace the project's CPU with another from the hardware catalog (e.g. 'BMX P34 2020' + '02.70').

List the project's DTM topology (DTM Browser): communication/master DTMs and their slave devices, with names, DTM ids, types, and bus addresses (IP for Modbus TCP / EtherNet/IP devices).

Add a DTM to the project topology.

Top-level communication DTM: leave parent_dtm empty (e.g. on M580 the CPU DTM 'BMEP58_ECPU_EXT' usually exists already). Slave device under a master DTM: set parent_dtm to the master's name and device_type_name to the catalog entry — e.g. add a generic Modbus TCP slave with device_type_name='Modbus Device' under the M580 CPU DTM. After adding, set its IP with set_dtm_address and configure scan requests with get/set_dtm_dataset or set_dtm_control_parameters.

Delete a DTM (and its children) from the topology by name.

Set a slave DTM's bus address — for Modbus TCP / EtherNet/IP devices this is the IP address (e.g. '192.168.10.21'); for fieldbus slaves the node number. Optionally also set the device's gateway and subnet mask (the gateway must be in the same IP domain as the address or the build warns 'IP Address and Gateway address are not in the same domain'). Setting gateway/subnet rewrites the project archive: the project is reloaded and UNSAVED — build_project then save_project afterwards.

Read a master/communication DTM's control parameters as XML (CetControlParameterOutput schema): Modbus TCP I/O scanner lines with IP, unit id, timeouts, repetitive rate, and the ModbusTcpRequest entries (read/write start addresses and sizes).

Write a master DTM's control parameters (CetControlParameterInput XML) — scanner sizing and %MW mapping of the I/O scan. With build=True the DTM→PLC control information is rebuilt afterwards. Read the current values with get_dtm_control_parameters first and mirror the schema.

Export a DTM's full configuration dataset. For M580 master DTMs this is the XML dataset whose / nodes hold the Modbus scan lines (request read/write addresses, lengths, connection numbers, IO item names) — edit it and write back with set_dtm_dataset.

Import a slave DTM configuration dataset (previously exported with get_dtm_dataset, possibly modified).

Read the master/CPU DTM dataset XML — THE document holding the Modbus TCP scan lines (M580 DTMs XML Dataset spec).

Each scanned device is a under ; its holds one per scan line with Parameters attributes requestSettingBit (connection number), requestSettingRDAddress/RDLength, requestSettingWRAddress/WRLength, requestInputObjID/requestOutputObjID. dtm defaults to the first (CPU) DTM node.

Write back a modified master DTM dataset (adds/edits Modbus scan lines) and reload the project from the modified exchange archive.

To add a Modbus scan request, insert into the target SlaveDevice's a node shaped exactly like this (validated):

Rules (M580 CPU scanner): Index increments per request within the device starting at 0; requestSettingBit is the connection number (Modbus range 1-128, unique across the scanner); requestUniqueID must be a fresh GUID; requestInput/OutputObjID use an even/odd pair (n, n+1) from 1024-1279 per connection, 65535 for an unused direction; RD/WR address+length are in words (slave-index format, 0-based). After this call the project is reloaded and UNSAVED — run build_project to validate (the scan line then appears in get_dtm_control_parameters), then save_project.

Configure the M580 CPU's embedded Ethernet: main IP/subnet/gateway (+ ip_a/ip_b for the HSBY A/B addresses and ip_d for address D) and the Security-screen service flags.

Service args: -1 = leave unchanged, 0 = disable, 1 = enable. A remote EIO drop's CRA requires tftp, eip and dhcp_bootp ENABLED, otherwise the build fails with "CRA doesn't work when TFTP, EIP and DHCP_BOOTP settings are disabled". Updates every stored copy (application channel config words, DTM binary parameter container, DTM dataset XML) via a project-archive round-trip, so the project is reloaded and UNSAVED — build_project to validate, then save_project. For a slave device's gateway-domain warning use set_dtm_address(gateway=...) instead.

Start the Control Expert PLC simulator (sim.exe) so plc_connect can reach it. With enforce_security=False (default) the simulator's 'use default application (enforce security)' option is disabled in the registry first — otherwise sim.exe blocks on a warning dialog unless a password-protected default application is configured. Only use on a local test machine.

Stop the PLC simulator process.

List logical networks (Premium/Quantum: Ethernet, Modbus Plus, Fipway) with their IP service configuration where available.

Create a logical network (Premium/Quantum platforms; family e.g. 'Ethernet'). On M340/M580, configure communication on modules/DTMs instead.

Set the static IP configuration of a logical Ethernet network.

Make the Control Expert window of this automation session visible so a human can watch or take over. state: show_normal, show_maximized, minimize, restore.