inserted installation section in the guide

README.md

@@ -1,46 +1,81 @@
-$project
-========
+# Welcome to the IgH Master Userspace Real-time program tutorial by Mike Karamousadakis
 
-$project will solve your problem of where to start with documentation,
-by providing a basic explanation of how to do it easily.
+For any questions, send email to: mkaramousadakis @ zoho.eu
 
-Look how easy it is to use:
+For a full documentation, licence and other information, visit the following ReadTheDocs [link](https://ighmaster-userspace-program-in-ros.readthedocs.io/en/latest/).
 
-    import project
-    # Get your stuff done
-    project.do_stuff()
+In the tutorial we assume that an Ubuntu flavor 16.04 is used.
 
-More to add here
+## Installation process
 
-Features
---------
+**SUPER SOS :** The following manual will be extremely helpful for understanding the instructions given in this section. You should **definitely** read it before procceding. [Link](http://linuxrealtime.org/index.php/Main_Page).
 
-- Real time characteristics
-- EtherCAT protocol utilization
-- Working in a ROS environment (kinetic version)
-- Utilizes the main development framework for EtherCAT applications, IgH Master Kernel Module
+### 0. Preempt_RT Patch
 
-Installation
-------------
+First step to utilize the repository given, is to install the preempt_rt patch in the kernel. Note that in order to install the IgHM, the kernel should be up to 4.9. A proper guide for the installation procedure can be found in the following [link](https://ubuntuforums.org/showthread.php?t=2273355). After you patch the kernel (say 4.9), you will want to use some other configuration parameters in the build of the kernel. Therefore after step 3 and in the line of *make menuconfig* of the previous link,
+you will want to specify some extra configuration parameters, derived from the chapter 3 of the manual mentioned in the beginning, namely:
 
-More to write here.
-Stay tuned. 
-It will be intense.
+- CONFIG_PREEMPT_RT_FULL
 
-Contribute
-----------
+- CONFIG_CPU_FREQ=n
 
-- Issue Tracker: github.com/$project/$project/issues
-- Source Code: github.com/$project/$project
+- CONFIG_CPU_IDLE=n
 
-Support
--------
+- CONFIG_NO_HZ_FULL=y
 
-If you are having issues, please let us know.
-We don't have a mailing list yet, so the default way is by communicating with: mkaramousadakis@zoho.eu
+- CONFIG_RCU_NOCB_CPU=y
 
-License
--------
+The author has used only the first configuration parameter and has seen great boost in the performance of the real-time tasks specified. Future work requires more tweaks to be done, derived from the afore mentioned manual.
 
-The project is licensed under the GPLv2 licence. See more details in the source files of the project.
+#### Tip: While you are in the menuconfig, type "/" and you can type to find the place of a configuration parameter. Exit with ESC
 
+### 1. Installation of IgHM
+
+1. cd into the etherlab-mercurial folder
+2. Run *make ethercatMasterInstallWithAutoStart*. Note that root access is needed. If you use another native driver from e1000e, open the Makefile and change the configure option with your driver version. You can find [here](http://www.etherlab.org/en/ethercat/hardware.php) and [here](http://www.etherlab.org/download/ethercat/ethercat-1.5.2.pdf) (Chapter 9), the supported hardware and the options the command *configure* takes, respectively. If your hardware is not supported or if you don't want the native driver support fuzz, then you should change the *configure* command to enable generic driver support (although I think it defaults to that).
+
+
+### 2. Run the scripts
+
+1. Because we want to have a process in realtime context, we should change it's priority (done in the code -FIFO policy, 80 priority-). Besides that, the interrupt handler which handles the interrupts generated by the network driver, should have higher priority than the process we develop, so that the EtherCAT datagrams are ready to be sent/received before we process them. For that cause I have written a script, as a sample script, to change the priority of the irq process of the network card.This should be used accordingly to change **your** process's priority. You could check if the priority has changed with the *chrt* command. How-to can be found [here](https://www.cyberciti.biz/faq/howto-set-real-time-scheduling-priority-process).
+
+2. Aside from the enhancements proposed by the manual, we should also change the throttling of our network driver to 0. This is done in the script also in the *testbench* directory. It is based on my e1000e driver, so use it as a sample script. Documentation for the insertion of the module of the e1000e network driver can be found [here](https://downloadmirror.intel.com/15817/eng/readme.txt).
+
+3. Run the script for changing the permissions of ighm_ros. We set the suid of ighm_ros to be root, so that the ighm_ros can be launched without *sudo*. This will be useful **after** you *catkin_make* the project.
+
+## Example usage
+
+1. Before running the program, you could restart the ethercat service (the IgHM). To do that, run the following command:
+
+```bash
+$ sudo /etc/init.d/ethercat restart
+```
+
+The kernel logs can be very useful, because they show what is happening to the IgHM every time, how many packets he has skipped etc. To see the kernel logs, run the command:
+
+```bash
+$ tail -f /var/log/kern.log
+```
+
+2. After you *catkin_make* the project, in one terminal run:
+
+```bash
+$ roslaunch ighm_ros ighm_ros.launch
+```
+
+3. After that, and while the process is running, you run in another terminal:
+
+```bash
+$ rosrun ighm_ros ethercat_keyboard_controller.py
+```
+
+4. Now you can give orders to the EtherCAT Communicator via a custom terminal. Have fun!
+
+- *Tip: You could run a bash script in the custom terminal by running:*
+
+```bash
+[ethercat_controller] > !r my_awesome_bash_script.sh
+```
+
+Note that your script must be under the *scripts* directory. You could also check some
+example scripts there.

docs/source/guide.rst

@@ -15,15 +15,15 @@ $ roslaunch ighm_ros ighm_ros.launch
 $ rosrun ighm_ros ethercat_keyboard_controller.py
 
 
-- Now you can give orders to the EtherCAT Communicator via a custom terminal. 
+- Now you can give orders to the EtherCAT Communicator via a custom terminal.
 Have fun playing around!
 
 - *Tip: You could run a bash script in the custom terminal by running:*
 
 .. highlight:: bash
 [ethercat_controller] > !r my_awesome_bash_script.sh
 
-Notice that your script must be under the *scripts* directory. You could also check some 
+Notice that your script must be under the *scripts* directory. You could also check some
 example scripts there.
 
 Features
@@ -37,22 +37,56 @@ Features
 Installation
 ------------
 
-More to write here.
-Stay tuned. 
-It will be intense.
+**SUPER SOS :** The following manual will be extremely helpful for understanding the instructions given in this section. You should **definitely** read it before procceding. `Link <http://linuxrealtime.org/index.php/Main_Page>`_.
+
+0. Preempt_RT Patch
+~~~~~~~~~~~~~~~~~~~~
+
+First step to utilize the repository given, is to install the preempt_rt patch in the kernel. Note that in order to install the IgHM, the kernel should be up to 4.9. A proper guide for the installation procedure can be found in the following `link <https://ubuntuforums.org/showthread.php?t=2273355>`_. After you patch the kernel (say 4.9), you will want to use some other configuration parameters in the build of the kernel. Therefore after step 3 and in the line of *make menuconfig* of the previous link,
+you will want to specify some extra configuration parameters, derived from the chapter 3 of the manual mentioned in the beginning, namely:
+
+- CONFIG_PREEMPT_RT_FULL
+
+- CONFIG_CPU_FREQ=n
+
+- CONFIG_CPU_IDLE=n
+
+- CONFIG_NO_HZ_FULL=y
+
+- CONFIG_RCU_NOCB_CPU=y
+
+The author has used only the first configuration parameter and has seen great boost in the performance of the real-time tasks specified. Future work requires more tweaks to be done, derived from the afore mentioned manual.
+
+*Tip: While you are in the menuconfig, type "/" and you can type to find the place of a configuration parameter. Exit with ESC*
+
+1. Installation of IgHM
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. cd into the etherlab-mercurial folder
+2. Run *make ethercatMasterInstallWithAutoStart*. Note that root access is needed. If you use another native driver from e1000e, open the Makefile and change the configure option with your driver version. You can find `here <http://www.etherlab.org/en/ethercat/hardware.php>`_ and `here <http://www.etherlab.org/download/ethercat/ethercat-1.5.2.pdf>`_ (Chapter 9), the supported hardware and the options the command *configure* takes, respectively. If your hardware is not supported or if you don't want the native driver support fuzz, then you should change the *configure* command to enable generic driver support (although I think it defaults to that).
+
+
+2. Run the scripts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Because we want to have a process in realtime context, we should change it's priority (done in the code -FIFO policy, 80 priority-). Besides that, the interrupt handler which handles the interrupts generated by the network driver, should have higher priority than the process we develop, so that the EtherCAT datagrams are ready to be sent/received before we process them. For that cause I have written a script, as a sample script, to change the priority of the irq process of the network card.This should be used accordingly to change **your** process's priority. You could check if the priority has changed with the *chrt* command. How-to can be found `here <https://www.cyberciti.biz/faq/howto-set-real-time-scheduling-priority-process>`_.
+
+2. Aside from the enhancements proposed by the manual, we should also change the throttling of our network driver to 0. This is done in the script also in the *testbench* directory. It is based on my e1000e driver, so use it as a sample script. Documentation for the insertion of the module of the e1000e network driver can be found `here <https://downloadmirror.intel.com/15817/eng/readme.txt>`_.
+
+3. Run the script for changing the permissions of ighm_ros. We set the suid of ighm_ros to be root, so that the ighm_ros can be launched without *sudo*. This will be useful **after** you *catkin_make* the project.
 
 Contribute
 ----------
 
-- Issue Tracker: https://github.com/mikekaram/IgHMaster_userspace_program_in_ROS/issues
-- Source Code: https://github.com/mikekaram/IgHMaster_userspace_program_in_ROS
+- Issue Tracker: https://github.com/mikekaram/IgHMaster-userspace-program-in-ROS/issues
+- Source Code: https://github.com/mikekaram/IgHMaster-userspace-program-in-ROS
 
 Limitations / Steps Forward
 -----------------------------
 
 This program assumes that the actual control code of the robot is running in the EtherCAT slaves.
 Therefore there is no connection between this program and ros_control, although the intention of the author
-is to make this connection happen, for robots that do have a control api inside ROS. This of course means 
+is to make this connection happen, for robots that do have a control api inside ROS. This of course means
 that the ros_control module should communicate afterwards with this program, to send new data to the EtherCAT
 slaves. Needless to say, the EtherCAT slaves will have a much more passive role in this configuration.
 
@@ -65,4 +99,4 @@ We don't have a mailing list yet, so the default way is by communicating with: m
 License
 -------
 The project is licensed under the GPLv2 licence. See more details in the source files of the project or in
-the Lincence section.
+the Lincence section.