Monday, May 18, 2015

BeagleBone Black Development Part 6 - Remote Application Debugging With Eclipse

This tutorial shows how to debug a BeagleBone Black  application remotely using the Eclipse IDE. This is similar to a post I made last year but with updates for BeagleBone Black Rev. C and Debian Jessie on the host machine and on the board.

This is part six in a series of tutorials that show how to develop for Beaglebone Black starting from a new install of Debian Jessie on a host machine in Part 1, and Part 2.  Part 3 covers cross-tool setup for BeagleBone BlackBeagleBone Black kernel build steps are in Part 4 and installing Linux to eMMC using Micro SD is covered in part 5.

6.1 Install GDB server on the BeagleBone Black

A GDB server can use any IP connection to debug.  You can use ethernet port (eth0), the USB device port (usb0), a USB to Ethernet adapter on the USB host port (eth1) or a USB to WIFI device.  

See the USB gadget section of Beaglebone Black - Linux on ARM to set up usb0.

To use a USB-to-ethernet device in the host port, you need to build a kernel configured with drivers for your device.  The drivers can be found in menuconfig in Device drivers>Network device support>USB Network Adapters.

Connect the FTDI USB to serial port and log into the console and power up the Beaglebone Black.

The following commands with usernames that end with @arm are executed in the serial terminal program on the BeagleBone Black, not on the host used to cross-compile the kernel.

debian@arm:~$ sudo apt-get update
debian@arm:~$ sudo apt-get install gdbserver

6.2 Eclipse IDE Setup on Development Host

Eclipse is a large install package, it will take a little while to complete. Enter these commands on the Linux cross-development host machine.
user@debian:~$ sudo apt-get install eclipse eclipse-cdt  eclipse-cdt-launch-remote

Make a workspace for a test application.
user@debian:~$ mkdir ~/bbb/testws

Start Eclipse from the Applications Menu.  Be patient, the first run takes a long time to load.

Browse to the workspace directory we created and click OK.

Eclipse will come up with a welcome screen.  Select Window, click Open Perspective, Other...

Create a new C project using File, New then selecting C Project.

Name the project, select project type Hello World ANSI C Project, select Toolchain Cross GCC, click next.

The next screen asks for basic properties, you can just enter an author and click next.

The Select Configurations window will appear, click on Advanced settings.

In the settings window on the left hand side open up C/C++ Build -> Settings to bring up the Tool Settings tab for the Debug configuration.

Select Cross Settings.  Set the prefix to arm-linux-gnueabihf-  and set the path of the tools we installed earlier (Section 3.2).  If you created the armcc-vars file in that section it will show the path.  
user@debian:~$ cat ~/am335x/armcc-vars
export CC=/home/user/am335x/gcc-linaro-arm-linux-gnueabihf-4.9-2014.09_linux/bin/arm-linux-gnueabihf-
export ARCH=arm

In the example file above the prefix is arm-linux-gnueabihf- and the path to enter is:

Properties for bbb_hello_world.png

Click Apply, then click OK.  You should go back to C Project screen, click Next.C Project Next.png

You should see the next screen asking for the same values we just entered (seems like a bug in eclipse).  Just enter the values for prefix and path one more time and click Finish.

This brings up a workspace with the hello world C source file open.  Build the project using Project menu, Build All and you should see the prefix we entered being used for the tools (gcc).


You should not see any errors in the console tab at the bottom of the page.

6.3 Eclipse Remote Connection Setup

The eclipse remote connection will require some changes on the BeagleBone Black.  Make a serial port connection or ssh into a console.

First check the IP address of the port we will use for debugging.  Use the ifconfig command and write down the inet addr shown.  Ethernet port (eth0) information shown below.
debian@arm:~$ sudo ifconfig
[sudo] password for debian:
eth0      Link encap:Ethernet  HWaddr 1c:ba:8c:e1:7f:ae  
         inet addr:  Bcast:  Mask:
         inet6 addr: fe80::1eba:8cff:fee1:7fae/64 Scope:Link
         RX packets:22706 errors:0 dropped:0 overruns:0 frame:0
         TX packets:205 errors:0 dropped:0 overruns:0 carrier:0
         collisions:0 txqueuelen:1000
         RX bytes:1790146 (1.7 MiB)  TX bytes:23064 (22.5 KiB)

We will need ssh installed and running on the BeagleBone Black for eclipse remote debugging.

Test ssh from the development host machine using the IP address we just found for the port..
user@debian:~$ ssh debian@

If there are any problems check to make sure an ssh server is installed.
debian@arm:~$ dpkg -s openssh-server
If not install openssh server.
debian@arm:~$ sudo apt-get install openssh-server

If ssh is installed but you have trouble connecting to the board some host key files might be missing.
Check for ‘Could not load host key’ errors in /var/log/auth.log using grep.
debian@arm:~$ grep sshd /var/log/auth.log

If you see this problem you can regenerate the individual keys or just regenerate all by reconfiguring openssh server.
To reconfigure, first delete any existing host keys.
debian@arm:~$ sudo rm /etc/ssh/ssh_host_*
Next, generate all new key files.
debian@arm:~$ dpkg-reconfigure openssh-server

If for some reason you need to regenerate individual keys see Phillip’s Tech Blog: Could not load host key.

Once ssh is working from the host the next step is to add another user to the BeagleBone for the remote debug connection.

Create a user with the same name as the user you created for Debian on the host virtual machine.  In this document the name is just ‘user’ for simplicity.  To be clear, if you are logged in and running eclipse as a user ‘joe’ in the host debian virtual machine, you will create a new user named ‘joe’ on the BeagleBone Black to log in with eclipse ssh for debugging.  This might not be absolutely necessary, but I haven’t found the place to change the remote username, it seems eclipse expects the remote system to have the same username (but allows you to change the remote password).
debian@arm:~$ sudo adduser user
[sudo] password for debian:
Adding user `user' ...
Adding new group `user' (1001) ...
Adding new user `user' (1001) with group `user' ...
Creating home directory `/home/user' ...
Copying files from `/etc/skel' ...
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully
Changing the user information for user
Enter the new value, or press ENTER for the default
       Full Name []:
       Room Number []:
       Work Phone []:
       Home Phone []:
       Other []:
Is the information correct? [Y/n] Y
Adding new user `user' to extra groups ...
Adding user `user' to group `dialout' ...
Adding user `user' to group `i2c' ...
Adding user `user' to group `spi' ...
Adding user `user' to group `cdrom' ...
Adding user `user' to group `floppy' ...
Adding user `user' to group `audio' ...
Adding user `user' to group `video' ...
Adding user `user' to group `plugdev' ...
Adding user `user' to group `users' …
debian@arm:~$ exit

Debian GNU/Linux 7 arm ttyO0

default username:password is [debian:temppwd]

arm login: user
Linux arm 3.8.13-bone70.5 #1 SMP Wed Mar 11 16:37:28 EDT 2015 armv7l

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.

Create a workspace and project directory.
user@arm:~$ mkdir ~/remotews                                                  
user@arm:~$ mkdir ~/remotews/hello                                            
user@arm:~$ chmod a+w ~/remotews/hello/
Next we will set up the host using eclipse.  
On the Eclipse Run menu, click Run Configurations. Select C/C++ Remote Application, press the New launch configuration button.

On the next window the bbb_hello_world Debug run configuration is selected.  On the main tab click New.

run configurations connection new.png

In the New connection window for system type click Linux then next.  

In the next window we will enter the BeagleBone Black IP address for the host name and give a connection name and description.  

Enter the internet address of the port as the Host name.  Click the Verify host name box so it is not checked.

new connection description.png

In the next screen check the box for ssh.files and click Next.

In the Next window click the box for and click Next.

On the next screen click ssh.shells and Next.

The next window select ssh.terminals (should be default) and click Finish.

This will return you to the Run Configurations window.
In the Main tab, select BBB Ethernet for Connection then click Properties to the right.

Enter the path to the remote workspace and click OK.  

Next in the Main tab, enter the remote absolute path to the executable application binary.  The absolute path of the executable file will be /home/user/remotews/hello/bbb_hello_world.

Enter ‘chmod +x /home/user/remotews/hello/bbb_hello_world’  in the field ‘commands to execute before application’ to allow the executable to run after it is uploaded to the board.

After both values have been entered click Apply then click Run.  If Run is greyed out so you can’t continue then I have found it easiest to just delete the bbb_hello_world Debug configuration and back up a few steps to creating a new launch configuration.  You won’t have to re-enter the connection information but you need to enter the remote absolute file path and commands to execute again.
Click Run.  Wait a few seconds for the Enter Password window to appear.  Enter the username and password for the BeagleBone Black and click OK.

A secure storage window will appear, choose a password, this is an eclipse feature not required for the ssh connection.

Even though we entered save password above, a ‘Password required’ window might  appear for your ssh connection (possibly only the first time).  Enter the ssh username and password again to connect to the beaglebone black.

If an authenticity of host key warning appears, click Yes.

After a successful run the console will be displayed in the lower Eclipse window.  It will show the output of the remote program.
echo $PWD'>'
chmod +x /home/user/remotews/hello/bbb_hello_world;/home/user/remotews/hello/bbb_hello_world;exit
Last login: Thu Mar 26 15:43:10 2015 from earth
user@arm:~$ echo $PWD'>'
user@arm:~$ chmod +x /home/user/remotews/hello/bbb_hello_world;/home/user/remote ws/hello/bbb_hello_world;exit
!!!Hello World!!!

6.4 Eclipse GDB Debugging Setup

Open a terminal on the host Linux system.  Change to the Debug directory for the project and create an empty .gdbinit file.
user@debian:~$ cd ~/bbb/testws/bbb_hello_world/Debug/
user@debian:~/bbb/testws/bbb_hello_world/Debug$ touch .gdbinit

Open Eclipse, open the Run menu in the menu bar and click Debug Configurations. Select bbb_hello_world Debug under C/C++ Remote Application.

Open the Debugger tab.  This has three tabs for Debugger Options, click the Main tab.
debug configuration main tab.png

Click the Browse button for GDB debugger to find the gdb executable from the host toolchain (arm-linux-gnueabihf-gdb).  
debug browse gdb.png
Next click the browse button next to GDB Command file, to locate it you will need to Right-click to show hidden files to see it.  After you find it select it and click OK.

After entering the debugger and command file click Apply.
Now click Debug in the lower right hand corner of the Debug Configurations window to test the setup.  The first time you will get a confirmation window.

The Debugger will stop before the first line of the program.   Mouse over the icons to get descriptions of the debugger commands or use the Run menu.  See the Eclipse Help menu for more information on the Debug commands.

F6 will step over so you can see the !!!Hello World!!! output in the Console window.
Debug hello world success.png

If this works you are finished setting up eclipse.  You should be able to debug your own programs using this setup as a guide.


SAURABH said...


Thank you very much for writing this blog. I followed each steps provided by you to do Remote application debugging with eclipse and able to debug application on beagle bone black using debug configuration menu.

But this I am able to do only sometime. On other times I get error "Could not start gdbserver on the remote host. See console output for more details."

Please Note: I get this error only sometime. Can you please tell me reason for it and how can i fix it.

Thanks a lot for your help :)

Abu al-Sous said...

this actually worked; Many thx