Troubleshooting
Edge gateway online but PLC offline: diagnose the link
Short answer
Gateway online only proves the Automation Server can reach the gateway; it says nothing about the gateway-to-PLC session. Confirm the scan result, switch on file logging in /etc/Gateway.cfg under [CmpLog], reproduce the failure, and read /tmp/codesysedge.log at the failure timestamp. A reinstall that holds for about a month points at a returning state: certificate validity, clock drift, address change, or an overwritten configuration.
On this page
Gateway online, PLC offline is two different checks, not one fault: the Automation Server reaches the gateway process, but the gateway is not holding its session with the PLC. Stop before the next delete-and-reinstall. Confirm what a scan returns, switch on file logging in /etc/Gateway.cfg under [CmpLog], reproduce the failure once, and read /tmp/codesysedge.log at the failure timestamp. When a reinstall holds for about a month and the identical symptom returns, the cause is a state that expires or rotates — certificate validity, clock drift, a changed address, or an overwritten configuration — and the log names which one.
What the two states tell you #
Gateway online means the server-to-gateway half works: the gateway service is running and answering the Automation Server. PLC offline, or not connected, means the gateway-to-PLC half is failing: the gateway cannot reach the PLC's address, the device refuses the session, or the trust handshake does not complete. The flags separate those halves, so diagnose the second half on the gateway side, not in the server.
A scan cannot fix this. The PLC is already registered in the Automation Server, and a scan only lists devices that answer discovery. Its one use here is negative: if the PLC stops answering discovery too, the device itself is down and the fault moves from session setup to the controller.
| Observed fact | What it decides |
|---|---|
| Gateway online, PLC offline | Server-to-gateway path healthy; work the gateway-to-PLC session |
| PLC already listed, scan adds nothing | Registration is done; the fault is session state, not discovery |
| Reinstall held about a month, then identical failure | A state on a roughly monthly cycle, not a broken installation |
| Data missing downstream since the failure | The dead PLC link is starving consumers, not just a status flag |
The last row matters when the real complaint is lost data rather than a flag: a dead PLC link shows up downstream as an empty historian trend when PLC tag collection stops, and this same gateway session is what feeds it.
Turn on file logging first #
The logging target is /etc/Gateway.cfg, section [CmpLog]. Apply the settings exactly as the file expects them:
[CmpLog]
CmpEdgeGateway.Filter=0xFFFFFFFF
Logger.0.Name=/tmp/codesysedge.log
Logger.0.Filter=0x0000000F
Logger.0.Enable=1
Logger.0.MaxEntries=100000
Logger.0.MaxFileSize=5000000
Logger.0.MaxFiles=1
Logger.0.Backend.0.ClassId=0x00000104 ;writes logger messages in a file
Logger.0.Type=0x314 ;Set the timestamp to RTC
What each line buys: CmpEdgeGateway.Filter=0xFFFFFFFF opens the edge-gateway component's own messages at full mask, so connection attempts reach the logger. Logger.0.Enable=1 with Logger.0.Filter=0x0000000F records every severity class. Logger.0.Backend.0.ClassId=0x00000104 selects the file writer named in the file's own comment. Logger.0.Type=0x314 stamps entries from the RTC clock, so log times line up with wall-clock events and betray clock drift if that is the cause. The caps keep one file of up to 100,000 entries and 5,000,000 bytes, about 5 MB.
On release 4.14.0.0 of the CODESYS Edge Gateway for Linux, the release notes state that Gateway.cfg references an additional Gateway_User.cfg file maintained separately, so settings placed there survive a package update. Put the block in Gateway_User.cfg on that release, then restart the gateway process so the new logger settings load.
Reproduce once, then read the failure window #
Note the wall-clock time, trigger one connection attempt, and read /tmp/codesysedge.log for that window. You are looking for entries that name the PLC address or port, certificate or trust errors, authentication rejects, timeouts, and retry loops — the log names the failing step of the session.
Before chasing an old failure, check whether the log still reaches that far back, because the caps bound the history. Worked example with assumed values, not measurements: with Logger.0.MaxFileSize=5000000 in one file and a 200-byte average line, capacity is 5,000,000 / 200 = 25,000 lines. If the gateway retries once every 5 s, coverage is 25,000 × 5 s = 125,000 s, and 125,000 / 3,600 ≈ 34.7 h — about 1.5 days. A failure from a week ago is already overwritten; reproduce the fault now and copy the file off the gateway immediately, because /tmp does not necessarily survive a reboot.
Scale the example with your own measurements: coverage in hours = 5,000,000 / measured average line size × measured retry interval in s / 3,600. A retry loop ten times faster cuts coverage to a tenth, so measure both numbers from the captured file instead of assuming them.
Rank the causes a monthly relapse points at #
One confirmed recurrence is one data point, but a reinstall that holds for weeks and then fails identically narrows the field to states that expire or rotate. Test them in this order, each against the log captured above.
- Certificate validity. Read the certificate's not-after date and set it beside the two failure dates; if the gap matches the validity period, certificate or trust entries at those timestamps confirm it. Automation Server release notes list automatic certificate renewal for encrypted connections, so a deployment that predates that feature treats expiry as a scheduled failure. An expired or untrusted certificate kills session setup before the PLC address is even dialed — the same fault class behind a controller reporting not secure because its certificate is untrusted. Fix: renew or replace the certificate and put renewal in place.
- Clock drift. Logger.0.Type=0x314 stamps entries from the RTC, so compare a log timestamp with a reference clock at the same moment; minutes of drift on a box with no time source is the finding. Fix: restore time synchronization and confirm the stamps hold steady.
- Address change. Compare the PLC address the gateway dials with the device's current address at the failure time. A lease that turned over daily would fail daily, not monthly, so a one-month period fits an address change only if something in the network changed at the same time. Fix: pin the address or re-point the gateway at the current one.
- Configuration overwrite. Diff /etc/Gateway.cfg against the settings you applied, especially after a gateway update; on 4.14.0.0 the Gateway_User.cfg mechanism is what keeps your overrides in place. Fix: reapply the settings and move them to the user-maintained file.
The sequence to run #
Run the reproduce-and-capture step in a planned window: restarting the gateway drops every session it is holding, so do not bounce it while the cell is running. Then work down this list:
- In the Automation Server, confirm the PLC is still listed and showing offline or not connected. Skip the scan as a fix.
- Write down the failure date, time, and what changed nearby: updates, network changes, power events.
- Apply the [CmpLog] block, in Gateway_User.cfg on 4.14.0.0, and restart the gateway process.
- Reproduce one failure and note the wall-clock time.
- Copy /tmp/codesysedge.log off the gateway immediately.
- Read only the failure window: certificate and trust entries, address and port errors, timeouts, retry loops.
- Decide with the ranked tests: certificate not-after date first, then the clock comparison, then the address match, then the configuration diff.
- Fix the confirmed cause; re-register or reinstall only after the log shows why the session died.
- Verify: the Automation Server shows the PLC online, the scan result matches that state, and the log for the previously failing window now records a clean session.
- If the log carries plant addresses or certificates, send it through the CODESYS Store's 'my question' channel instead of posting it publicly.
The decision: treat the offline flag as a session fault on the gateway side, capture the log before touching the installation, and let the failure window choose among certificate, clock, address, and configuration. The reinstall that holds for weeks is not a fix; it resets a timer that is still running.
Questions asked
Why did deleting and reinstalling the gateway fix it for about a month?
The reinstall reset state that expires on its own schedule, certificate validity above all, but also DHCP leases, clock drift, or a configuration later rewritten by an update. When the same symptom returns after roughly a month, compare the certificate's not-after date with the two failure dates first. The reinstall was never the fix; it restarted a countdown.
How do I keep more log history between failures?
Raise the retention in the same logging block: Logger.0.MaxFileSize=5000000 and Logger.0.MaxFiles=1 keep a single file of 5,000,000 bytes, so a larger MaxFileSize or a MaxFiles above 1 stretches coverage. Keep Logger.0.Type=0x314 so entries stay stamped from the RTC and still line up with wall-clock events days later.
The log shows nothing around the failure time. What now?
Check that logging was actually active in that window: Logger.0.Enable=1 set, the CmpEdgeGateway filter mask in place, and the edits made in the file the running gateway reads. On release 4.14.0.0 that can be Gateway_User.cfg rather than Gateway.cfg. Then restart the gateway process, reproduce once, and confirm new entries appear before reading for a cause.
Does rescanning the network bring the PLC back online?
No. Discovery and session establishment are separate: a scan finds what answers, while the offline flag reflects the gateway's failed session with a PLC it already knows. That is why the scan result looks unchanged even while the fault is active, because the device answers discovery fine while its session stays down.