Explainer
Editing a CODESYS Raspberry Pi PROFINET controller project
Short answer
A Raspberry Pi running CODESYS Control executes the compiled application you download to it; it cannot import GSDML, rebuild the project, or safely change I/O or OPC UA mappings on its own. Keep the CODESYS Development System on Windows as the editing tool, deploy builds to the Pi, and reserve the runtime on the controller for execution.
On this page
- The runtime executes, the development system edits
- Why adding a PROFINET device cannot happen on the Pi alone
- A worked example: sizing a new device's process image
- Logic and OPC UA changes: same tool, different objects
- The workflow that keeps the Pi and the project in agreement
- The decision, case by case
- Questions asked
No — the Raspberry Pi in a CODESYS PROFINET setup has no project editor to switch on. The Pi runs CODESYS Control, the runtime the vendor documents as the SoftPLC counterpart of its development system, and its job is to execute the application an engineering tool compiles and downloads. Every change on the wishlist — importing a device's GSDML, adding devices under the PROFINET controller, re-mapping I/O, publishing different OPC UA data, editing the control logic — is a project operation, and project operations start in the CODESYS Development System on Windows. Keep the split: edit and build on the engineering station, deploy to the Pi, and treat the runtime as the thing that runs the result. The sections below cover what each side does, why a device addition cannot happen on the controller, a worked process-image example, and the workflow that keeps the deployed build and the project in agreement.
The runtime executes, the development system edits #
CODESYS Control SL is documented as the runtime system for the CODESYS Development System — the component that turns an intelligent device into a SoftPLC. A Raspberry Pi setup follows the same pattern: a runtime package executes the compiled application, while the development system on Windows owns the project. The project holds the device tree, the network identities, the I/O mappings, the program organization units and the variable selection the runtime's OPC UA server publishes; the runtime holds none of it in editable form. That is the same separation that makes the engineering tool a distinct product in other ecosystems; what STEP 7 is in a PLC project, and which one you need covers the equivalent split for Siemens hardware.
| Change you want | Where it is made |
|---|---|
| Import a GSDML device description | Engineering system device catalog |
| Add a PROFINET device and its modules | Project device tree |
| Change I/O mappings | Project, then download |
| Change the OPC UA variable set | Project, then download |
| Edit application logic | Project; download or engineering-initiated online change |
| Install or update the Pi runtime | Pi-side installer tooling, not the project |
Even the Pi-side housekeeping is separate tooling, not editing: the vendor's first-steps documentation notes that the "Update Raspberry Pi" tool no longer exists as of version 4.14.0.0, with runtime setup and updates moved to the installer path. The PROFINET controller capability itself is a package delivered through the CODESYS Store and the CODESYS Installer — a deployment and licensing step, not a project edit.
Why adding a PROFINET device cannot happen on the Pi alone #
A GSDML file is an XML device description. Importing it teaches the engineering system's device catalog what the device is — its modules and submodules, the data width of each, its diagnostics — and only then can the device be placed under the PROFINET controller in the device tree. The import target is the engineering tool, not the runtime: CODESYS Control consumes the compiled configuration that arrives with the download and has no catalog to import into and no device tree to edit. A device addition is therefore a project operation:
- Get the GSDML that matches the device variant and firmware you actually run, from the manufacturer or its distributor.
- Import it into the device catalog and confirm the device appears with the modules its documentation lists.
- Add the device under the PROFINET controller in the project, set its PROFINET name and address, and select its modules.
- Map the new channels to variables, checking every direction, data type and offset.
- Compile, download to the Pi, and confirm the device exchanges data before trusting the values.
Step 4 is where existing projects get hurt: new bytes can shift addresses that other code depends on, and a changed GSDML revision can change widths. Updating PROFINET GSDML without losing I/O mappings walks through keeping the mapping layer intact while the description underneath it changes. None of the five steps has a Pi-side equivalent, because none of them operates on files the runtime can read.
A worked example: sizing a new device's process image #
Illustrative example — the module widths below are the example's assumption, not a catalog entry; read the real widths from the imported device description. Suppose the new device carries 16 digital inputs, 16 digital outputs, 4 analog input channels and 2 analog output channels, with digital channels packed eight per byte and every analog channel one INT.
Input side: 16 digital inputs = 16 bits ÷ 8 bits per byte = 2 bytes. Four analog channels × 2 bytes per INT = 8 bytes. Total input data = 2 + 8 = 10 bytes.
Output side: 16 digital outputs = 16 ÷ 8 = 2 bytes. Two analog channels × 2 bytes = 4 bytes. Total output data = 2 + 4 = 6 bytes.
The decision from those inputs: the device occupies 10 bytes of the controller's input process image and 6 bytes of its output image, and both numbers are fixed by the module definitions in the GSDML — nothing on the runtime computes or re-places them. The mapping editor in the engineering system assigns those bytes, and the download carries the result. If any variable is mapped at a fixed address, everything placed after this device moves by 10 input and 6 output bytes unless the layout is planned first, which is one more reason the change belongs in the project with the before-and-after addresses written down.
Logic and OPC UA changes: same tool, different objects #
Logic edits happen in the project's program organization units, in the editors the development system runs under Windows. The engineering system is also where language-level traps surface: a CODESYS timer that works in structured text but not in ladder is a documented example of logic that compiles clean and still fails on the target, so retest retimed or ported POUs on the Pi rather than trusting the build alone. An online change can carry a logic edit to the running controller without a full download, but it is started from the engineering system over the network and covers application code only — never devices, mappings or the OPC UA set.
The OPC UA side follows the same rule. The runtime serves the variables the project selects for publication; which variables appear, and with which names and types, are project settings. Changing what clients see means editing the selection in the project, compiling and downloading — the runtime serves the old set until that download lands. Verify from the client: connect, read the changed variables, and confirm names, types and values before any consumer cuts over.
The workflow that keeps the Pi and the project in agreement #
- Baseline the deployed build: record which project version is on the Pi and start every edit from that file.
- Save a dated, recoverable copy before the first change so the running baseline stays identifiable.
- Make the complete change set in the project — device additions, mapping edits, OPC UA selection, logic — instead of spreading partial downloads across a commissioning window.
- Compile for the Raspberry Pi target and clear every error; treat unresolved configuration references as blockers.
- Take the process to a safe state, then download over the network connection — the download replaces the application the runtime is executing.
- Verify in order: device status in the runtime diagnostics, mapped process values against the real signals, then the OPC UA view from a client.
- Archive the verified build and mark it as the deployed baseline so the next edit starts from what is actually running.
The decision, case by case #
Keep the engineering work on the machine that already has the toolchain: the development system with the device packages and target support for the Pi. If that station must live at the line — cabinet door or console, next to the controller it programs — that is the moment to choose hardware for it, and an industrial panel PC is the machine built for that slot. The Pi itself plays the fieldbus master role, and how to select a CODESYS fieldbus master for industrial Ethernet treats that hardware selection in full.
Per case:
- Add a PROFINET device: engineering system only. GSDML import, catalog check, device tree, module selection, mapping, compile, download — there is no Pi-side equivalent.
- Change I/O mappings: project, then download, with before-and-after addresses recorded.
- Change the OPC UA data set: project, then download, verified from a client before consumers switch over.
- Edit application logic: project; a full download for complete builds, an engineering-initiated online change for code tweaks between builds.
- Edit without a Windows desktop: evaluate the vendor's web-based CODESYS 4 environment, which runs on edge servers, in the cloud, on standard PCs or on PLCs, as a separate product with its own licensing — the Pi runtime is not an editor and cannot be turned into one.
Questions asked
Does the application keep running on the Pi while I edit on the engineering station?
No. Editing, compiling and saving happen on the engineering station, and the controller sees nothing until a download or an online change arrives from it. A full download replaces the application the runtime executes; an online change swaps code into the running program without one, but it covers application code only — never devices, mappings or the OPC UA set — and it is triggered from the development system too. There is no Pi-side command that pulls an edit in.
What does the Pi need before it can act as a PROFINET IO controller at all?
A supported runtime installation plus the licensed PROFINET capability, which the vendor licenses per device under its application-based licensing model. Both are deployment and licensing steps done with the vendor's tools, separate from project work. A project full of PROFINET devices is dead weight on a runtime that lacks the licensed controller capability, and no project file or configuration edit on the Pi can add it.
Where does a GSDML file come from, and how do I know it is the right one?
From the device manufacturer or its distributor, matched to the exact variant and firmware generation you actually have. The file name alone is not proof: different firmware generations of one product family can ship different GSDML revisions with different module layouts and data widths. Import the file, then check that the modules and widths the catalog shows match the device documentation before adding the device to the project.
Can I edit the project from a browser instead of a Windows desktop?
Not with the runtime. Browser-based engineering is a separate product in the vendor's catalog, published as CODESYS 4 and served over the network from its own host, so it needs its own evaluation and licensing. Installing it changes nothing about the Pi runtime, which still only executes what an engineering tool downloads to it. If browser editing is a hard requirement, that product is the documented route to test.