C++ remote debugging

Suitable with AXC F x152

PLCnext Technology has an integrated GDB server, so you can set up a remote debugging session using the Eclipse® IDE. Read more about the GDB server if you're new to this tool or interested in the complete functionality of this tool.

Setting up the station for a remote debugging session takes some time, but remote debugging your C++ code on your PLCnext Control will be a very useful feature that's worth the effort.  Most effort goes into the Debug configuration, and once you finished that for your station, the rest is quite as simple as you perhaps already know it as an experienced developer. 

Note: By now, this remote debugging procedure cannot be performed on a safety-related controller due to untouchable safety tasks.

Tutorial video


Note: Tutorial videos are embedded from the Phoenix Contact Technical Support YouTube channel.  With playing an embedded YouTube video in this platform, you accept the YouTube Terms & Conditions.
Depending on your personal settings in the Cookie consent dialog you may have allowed cookies for marketing purposes which will remain on your device. The data gained through this will be used by YouTube to provide video suggestions and advertisements based on your browsing habits, and may be made available to other parties. 

How to set up a remote debugging session for C++ programming with Eclipse® version 2019-03 (Neon)

Step-by-step instructions

Note: The above tutorial video and the following step-by-step instructions differ in these regards:

  • In the video, the Eclipse IDE version is 2019-03. The screenshots in the instructions below are of an older Eclipse® version, but the options are still the same.
  • In the video, Frank chose a slightly different route to start debugging after setting up the Debug configuration; both ways are similarly successful


Software to use:

  • Phoenix Contact Eclipse® Add-in 2020.0 LTS
  • Eclipse® 2019-9


  • These instructions are based on the Firmware 2019.x of the AXC F 2152.
  • The task watchdogs must be deactivated (0 ms) during the debug session.
  • The shared library must be created in Debug build mode.
  • The shared library (.so file) on the host system (Eclipse workspace) and on the PLCnext Control target must be the same.
  • The overall performance between steps can take a few seconds.
  • For some steps you'll need root or admin user privileges;  as admin user, please use the sudo precommand.

Debug Configuration

  1. Open your C++ program in the Eclipse IDE.
    Note: Make sure to meet the prerequisites regarding the Eclipse versions that these instruction are based on.
  2. Start the debug configuration by the Run → Debug Configurations... menu:
    Debug Configuration
  3. Create a C/C++ Remote Application by double-clicking the list item:
    Debug remote application
  4. On the Main tab that shows up in the right section of the dialog box,
    1. insert the path to the C/C++ application executable, e.g.:
    2. Set the "Build Configuration" drop-down menu
      to Debug (in Eclipse Neon):
      Debug Settings
      to Use Active (in Eclipse Photon):
      EclipsePhoton MainConfig
    3. Click the Select other link (same in both Eclipse Neon and Photon).
  5. In the Select Preferred Launcher dialog box,
    choose GDB (DSF) Manual Remote Debugging Launcher and close with the OK button:
    Manual remote debug launcher
  6. Back in the Debug Configuration dialog, switch to the Debugger tab, Main subtab:
    1. make sure to have enabled the check boxes shown here:
      Attach to process with 2022.0 LTS or newer
    2. As the  GDB debugger, insert the command to execute a specific .bat file and just the file name of the gdb executable, e.g.:
      cmd /c C:\PLCnext\SDKs\AXCF2152\2021.0_Release\environment-setup-cortexa9t2hf-neon-pxc-linux-gnueabi.bat && arm-pxc-linux-gnueabi-gdb.exe
    3. As the GDB command file, create a gdbinit.txt file containing the following handles and add it:
      handle SIGUSR2 nostop noprint 
      handle SIGILL nostop noprint 
      handle SIGSTOP nostop noprint
  7. On the Shared Libraries subtab of the Debugger tab, insert the directory of the shared library to debug.
    Usually, the library of a Eclipse project is saved in the Debug or Debug\lib subdirectory to a program.
    Shared libraries
  8. On the Connection subtab of the Debugger tab,
    1. insert a host name or IP address of the remote target
    2. insert the port on which the GDB server instance is listening
      Debugger connection
  9. Click the Close button.


Attaching to the remote GDB server

Risk of personal injury or damage to equipment

Using the debugging function can result in an unsafe process interruption.

Ensure that there is no risk of personal injury or damage to the equipment.


  • When executing the gdbserver --attach command, the whole PLCnext task will go into Stop mode, so the OUT ports will stand still and the remote connection to PLCnext Engineer will be interrupted.
  • After debugging, the PLCnext task will remain stopped (i.e. detached or disconnected in Eclipse®) and has to be restarted manually:
    • issue the /etc/init.d/plcnext restart command from the shell
    • or restart the controller by pressing the Reset button on its housing
    • or switch the current off and on again.
  • A breakpoint in GDB will stop the cyclic task only, so all other programs will keep running.
  • A breakpoint in PLCnext Engineer prohibits the call of C++ programs, so all tasks controlled by the ESM will stop.


  1. Log into a shell session on the remote system.
  2. Determine the process ID of PLCnext Technology process:
    1. With firmware 2019.0 LTS to 2019.9, issue this command:
      ps | grep Arp.System
    2. From 2020.0 LTS, issue this command:
      ps aux | grep Arp.System
  3. Start the gdbserver and attach it to the desired port:
    sudo gdbserver :2345 --attach <your process ID here>
    resulting in this answer if successfully attached:
    Grep Arp System answer


Setting the breakpoints and starting a debug session

  1. Select the newly created debug configuration by means of the "Debug" menu icon:
    Start Debug
  2. It might happen that warnings or errors are displayed after starting the debug session.
    1. Warnings in Eclipse® Neon:
      Prevent that by checking Always launch without asking  in the dialog box:
      Failure Debug 1
    2. Warning in Eclipse® Photon:
      Prevent that by checking Remember my decision in the dialog box:
      Eclipse Photon Confirm Switch
  3. The Eclipse debug view appears where you can add breakpoints and step through your code:
    Debug window
    1. For actions in this environment, please refer to the Eclipse Neon Online Help or the Eclipse Photon Online Help.






•  Web browser recommendation: Chrome/Edge 88 or newer, Firefox ESR 90 or neweror Safari • 
• Published/reviewed: 2022-09-14 • Revision 046 •