LinuxCNC Documentation Wiki: EMC Ubuntu91

Step by step: From bare metal to a working EMC2 installation on Ubuntu 9.10 with SMP - specifically for an Atom dual Motherboard

Instructions to get to EMC2 installed and running on Ubuntu 9.10 with SMP (verified on a Intel Atom 945GCLF2 and also an Intel Atom D510 MITX board based computers with sata drive)

Assumptions:

You are installing this software on a PC with enough basic resources, say at least a Gig of memory and 40 Gigs of drive space.
Hyperthreading is disabled on the CPU bios.

Precursor notes:

The system install has only been verified with this exact setup.
When in doubt do a "sudo make clean" before doing a compile (make) if you have done a compile of the same package before.
When you get lost, roll back your commands in the terminal window via the up and down keys so you can remember what you last did. Also helpful to avoid typing the same commands over and over again.
Read the output of the terminal window as a command completes before you forge ahead so you can detect any errors that have occurred.
If you see permission denied: you probably forgot the "sudo"
If you install something and things don't work, try typing "dmesg" at the command line to see what what happened.
You need to be on a fairly fast internet connection to allow this setup procedure to work without taking naps between downloads.
Linux is case sensitive. Remember ... Linux is case sensitive!
Google is your friend.. get stuck.. Google the error or situation.
The EMC2 folks want to help you.. Check out the EMC IRC channel, the email list, and the forum.
This is bleeding edge stuff. If you can't tolerate some frustration.... stick with the current EMC2 live CD install!

1. Download the Ubuntu 9.10 Live CD iso image, burn the cd and install it on your Atom dual core based computer.

2. Reboot. Now you should have a running Ubuntu 9.10 system and everything should be stable. If it is not stable now, making a new custom kernel will make not make things better. Try it out, surf the web, fire up some apps, make sure it is stable.

3. Update and upgrade everything:

		At the terminal command line:
		sudo apt-get update && sudo apt-get dist-upgrade

4. Set the root password to something simple that you can remember ... via System, Users and groups, click on root and change password via properties.

5. Install the following packages via apt:

	sudo apt-get install build-essential fakeroot debhelper libpth-dev 
	libgtk2.0-dev kernel-wedge tcl8.5-dev tk8.5-dev bwidget python2.5-dev 
	python-tk python-dev libglu1-mesa-dev libgtk2.0-dev libgnomeprintui2.2-dev 
	libncurses5-dev libxaw7-dev gettext libreadline5-dev lyx texlive-extra-utils 
	imagemagick tetex-bin tetex-extra groff qt3-dev-tools

	Reboot the computer.

6. The Ubuntu 9.10 system that you have just installed will be the platform on which you will create a new kernel that has a matching Realtime patch already established for it (as of Jan 18, 2010). Note that this new Kernel will actually be a little older than the version you just installed with the LiveCD?. This is important to know in order to avoid confusion as this process continues.

7. Preparing to create a Linux kernel that can be patched with the latest RTAI real time extensions:

	Fetch the kernel source you will use for the build (if you need ext4 file system support, you need this kernel source tarball).  
	At the terminal command prompt:
	cd /usr/src && sudo wget ftp://kernel.org/pub/linux/kernel/v2.6/linux-2.6.29.4.tar.bz2 && sudo tar xjf linux-2.6.29.4.tar.bz2 && 
	sudo mv linux-2.6.29.4 linux

8. Fetch this kernel configuration file: [kernelconfig.txt]

	Copy this file into the /usr/src/linux directory.  Rename the file ".config".   Delete or overwrite the any existing .config file.  An easy way 
	to do this is to do it via the Ubuntu GUI.  First log in as "root" and copy the file via edit copy paste etc.  Right click - properties, 
	will allow you to rename it easily.  Note that .xxxx files are
	hidden files in Linux.  Go to view, click on show hidden files so you can see them in a window.

9. Fetch the RTAI (realtime extensions code)and patch the kernel source code:

	sudo wget --no-check-certificate https://www.rtai.org/RTAI/rtai-3.7.1.tar.bz2 && sudo tar xjf rtai-3.7.1.tar.bz2 && cd linux && 
		sudo patch -p1 < ../rtai-3.7.1/base/arch/x86/patches/hal-linux-2.6.29.4-x86-2.4-01.patch

	Note that the patch version used needs to match the kernel source code version - as it does in the command line above.

10. Configure the Kernel compile by setting the .config file.

	In the terminal window:

	cd /usr/src/linux
	sudo make xconfig

	If using the supplied .config file and running an Atom dual core CPU the existing settings should be fine.

	Save, and exit.  If there are no errors...

11. Compile the kernel:

	sudo make clean && sudo make && sudo make modules_install && sudo make firmware && sudo make firmware_install && 
	sudo make headers_check && sudo make headers_install  (you may be asked for a password during this process.. )

	If no errors then:
	Install the kernel by copying the compiled kernel into the boot directory:

	sudo cp arch/x86/boot/bzImage /boot/vmlinuz-rtai

12. Almost ready to try out the new kernel:

	You need to modify the Grub boot menu and add the new kernel as a boot option.
	The Grub configuration file is not suppose to be altered directly with this latest version of Ubuntu, so download 
	another application called StartupManager?:

	sudo apt-get install startupmanager

	Then run the startup manager.  It should automatically find your new kernel that you copied to the /boot directory and you should see it.
	Check it as being the default startup kernel.

13. Restart the computer.

14. When it comes up (assuming that it did) go to a terminal window and type: uname -a You should see the version showing as the one you compiled:

	 linux-2.6.29.4  and it should say PREEMPT SMP.

	If you have a kernel panic (things are not right and it will not run), power cycle the computer and when the word GRUB shows up in the top left
	of the screen push down the shift key and hold it down.  A menu will pop up, select a non-rtai kernel to run so you can go back and reconfigure and
	recompile the kernel as somethig was obviously wrong.  :-(

        If you get an error saying that it cannot load the i810 module, see the note at the end of this page.

	Otherwise: At this point your PC is running on the kernel you patched and compiled.

15. Although you patched and compiled the kernel source code, you need to compile the RTAI real time code modules so they can be loaded when needed into the Linux

	kernel that you patched.  The RTAI compile is dependant on the Linux configuration settings.  So if you make a change to the kernel down the
	road, and recompile it don't be surprised if EMC2 fails to run since the RTAI also needs to be recompiled to match the kernel compile.

	So compile the RTAI modules:

	cd /usr/src/rtai-3.7.1
	sudo make xconfig

	All that should be modified here is the number of CPUs.  
	Ensure directories are correct:

	Installation: /usr/realtime
    	Kernel source: /usr/src/linux
    	Under Machine, choose number of CPUs (it should be set to two (2).  You can check the number you have running via "cat /proc/cpuinfo".  
	Exit and watch the configuration process...

	My configuration script failed - the linux source path was not found (I think there are a few bugs in the RTAI configure script)

	I got around this by running this:

	cd /usr/src/rtai-3.7.1
	sudo ./configure --with-linux-dir=usr/src/linux --disable-leds

	If you have no errors showing, then install the software:
	(Note - Do a "sudo make clean" if you have compiled this before)

	sudo make
	sudo make install

16. Now test the real time system:

	cd/usr/realtime/testsuite/kern/latency
	sudo ./run

	You should see a script run and number log to the screen.  Look for Max latency - about the 6th column from the left.  It should be less than 10000.
	If you don't something is wrong, the Linux kernel config probably does not agree with the RTAI config or else RTAI simply does not like your 
	configuration.

17. OK at this point you have a new patched kernel and the realtime system is working ok. Now to get to EMC2!

18. Get a copy of EMC2 source code, and configure it:

                go to http://sourceforge.net/projects/emc and download the latest version of EMC2 and make sure it ends up in 
                  /usr/src  (you might want to log in as root and copy the file to this location)
                cd /usr/src

		tar zxf emc2_2.3.5.tar.gz && cd emc2-2.3.54 && cd src && ./configure --prefix=/usr

19. If you don't get any errors compile it:

		Note:  I got an error saying that Python needs TCL 8.5 and TK 8.5 but when I checked my system with the synaptic manager it was already installed,
			so I ran the ./configure again and added these commands so it could find the TCL 8.5 and TK 8.5:

				The entire command line was:   ./configure --prefix=/usr --with-tclConfig=/usr/lib/tcl8.5/tclConfig.sh 
											--with-tkConfig=/usr/lib/tk8.5/tkConfig.sh

20. If no errors, compile it: (remember if this is a retry, do a "sudo make clean" first)

		sudo make

21. Install it:

		sudo make install

22. Restart the computer.

23. Run emc2:

emc

24. If it runs, you are getting close.

25. Now setup a quick emc2 configuration:

		I did it with "stepconf" run at the root directory.

		cd /
		stepconf

		Just setup a mill and tell just keep clicking next and you are done.  This will create a LPT port driven
		EMC2 configuration on your desktop.

	Run the EMC2 configuration.

	If it does not run, look at the error windows and see if it is having difficultly 
		creating or accessing shared memory as my computer was.

	This is a common Ubuntu software security situation with RTAI.

	Edit your login configuration file:

	It is located here:
	/etc/security/limits.conf

	Edit the file and make sure there are two files lines in it that look like this:

		* soft memlock 10240
		* hard memlock 10240

	Save the file after editing it.

26. The next issue that I ran into was that the parport_pc module and the lp module was being loaded when the OS loaded up

	and that was causing problems for EMC2 so it could not load the real time parport module which is used to 
	drive the parallel port.

	The best solution I could find was to blacklist these two modules so they would not load up at boot time.

	login as root
	go to /etc/modeprobe.d 
	edit the file called blacklist.conf
	at the top of the file add the following two lines to the top of the file:

	blacklist lp
	blacklist parport_pc

	Save the file and reboot

27. With these versions of the software there is a bug that causes the EMC2 latency-test program to hang up.

	When logged in as root, do a search for a file called vcpparse.py and edit it.
	At line 24 you will find 
	"import xlm.dom.ext"

	Edit this line and comment it out.  Put a # sign in front of the line, or simply delete the line all together.
	That line is not needed with this version of Ubuntu.

	Save the file.

	Run the latency-test program:

	cd /
	latency-test

 	You will see about 11,000 for the servo jitter and 11,000 for the base jitter with an SMP config on an Intel 330 motherboard.
	Also the user interface will be sluggish.

	EMC2 realtime is now using both cores which is not efficient.

28. To make the realtime components on only 1 cpu (the highest numbered one), go to /boot/grub and edit the grub.cfg file and add "isolcpus=1" to the first menuentry boot line

	(about line 53).  When you are done, the line should look like this:

	linux  /boot/vmlinuz-rtai root=/dev/sda1 ro isolcpus=1 vga=769 quiet splash

	This file is not suppose to be edited directly however I don't know how get this changed like this otherwise.
	This change will tie the EMC2 program to the second core.  I believe it is set for read only also, so you will need to change the permissions 
	via property, permissions.  Do that when logged in as root.

	Save and reboot.

	If you look at the performance monitor you will not see the realtime
	functions affect that core, as they don't show up on the graph.

26. Reboot your computer, log in and try running emc again.

27. Run the latency test via:

	cd /
	latency-test

	Exercise the computer, run GLX gears, surf the web etc to get some realistic latency numbers.
	I've been getting max numbers of about 3800 for the servo thread and 4050 for the base thread.

	Now you should be up and running with EMC2 on Ubuntu 9.10 with a low latency setup!!

Note Relating to "cannot load the i810 module" error when first booting compiled Kernel:

There is a problem that seems to be common with the Intel D510MO board and Ubuntu 9.10. Upon boot up the default intel video driver that is suppose to be compatible with the GMA 3150 onboard graphics malfunctions. The intel driver is suppose to communicate with the connected screen and find the available resolutions and refresh rate. But the driver fails and the result is the "cannot load the i810 module" error.

The fix: Start up the PC and when the error window pops up that says that it cannot load the i810 module, go into low resolution mode

Log out and then log in as root

go to /etc/X11

Open the file named: xorg.conf.failsafe.

Do a save-as and save it as "xorg.conf" in the same directory.

Then edit the xorg.conf file to make the "Monitor" section look like this:

	Section "Monitor"
		Indentifier	"Configured Monitor"
		HorizSync?	74.54
		VertRefresh?	60.0
	EndSection?

Then save the file.

The HorizSync? and VertRefresh? numbers above assume that your screen can support 1600x1200 resolution at a 60 hz refresh rate.

If it cannot, find the maximum horizontal and vertical resolution of your screen.

The specs may be 1280 x 768 at 60 hz for an older screen.

Then at a terminal window enter:

cvt 1280 768 60

find the hsync value in the results and enter that value in the xorg.conf file for the HorizSync? value.

Save the file.

Restart the computer with a power off-on restart. (Just a restart will not work) The computer will now startup using the vesa driver at the frequencies specified instead of trying to derive the video settings by communicating with the monitor. Ubuntu 9.10 and apparently also 10.4 have some issues with properly identifying the video settings possible when running on Intel IGP boards. (Although this configuration is running on a D510MO board with Ubuntu 10.4 without these video issues) Creating and setting this xorg.conf file basically overrides the automatic identification process and shortcuts the problem.

(Much of the info in this note was derived from this webpage: http://ubuntuforums.org/showthread.php?t=1324239 )

	Acknowledgements:
	This information was derived from probably more than 30 different sources including a number of different websites, other contributions
	on this Wiki, a number of people on the IRC and Email list, etc.   It involved a lot of serious head banging.  Thanks to everyone who helped.  
	I hope this can help many others as well who wants a fast, yet inexpensive, EMC2 system that can run on the inexpensive Intel Atom dual core boards. 
	Dave911 / Dave Cole  Please contact me if you see errors, omissions, or if anything can be improved etc.    email:  Dave at Colecontrols dot com