ROS LoCoRo SD Card
There are two software architectures available for the LoCoRo - Python and ROS.
  • The Python system - easy to program, lightweight, and is designed for the hobbyist, fun competition, and users interested in STEM learning and programming.
  • The ROS system - focused on research and development of fully autonomous systems. If you are not sure, then choose the Python system.

The two systems are capable of serving either goal and in fact, many people develop for ROS using only Python (ROS supports a number of development languages).

The following section creates an SD card for the ROS LoCoRo. If you want to create a Python LoCoRo system, use the Python SD Card documentation

The LoCoRo software is coded using ROS (robot operating system) running on the Ubuntu Linux operating system. The software is stored on a micro SD card installed on the Raspberry Pi 3 or Orange Pi Lite. In addition to Ubuntu and ROS, a few software packages are added to enable useful features such as a web interface and stand-alone wireless operation.
Throughout this section, there will be a combination of instructions, links, and commands. The text will be formatted as follows:
  • this is an example of an instruction with a special notation
  • this is an example of a link to software that is downloaded from the internet
  • this is an example of a Linux command or response to be entered in a console or terminal window

The LoCoRo project is designed for the Raspberry Pi 3. There is an Ubuntu image for Raspberry Pi 2. It has not been tested.

As an alternate, the LoCoRo project is tested on the Orange Pi Lite. Where necessary, the documentation specific to different hardware will be highlighted.

Warning: It is not advisable to log into a Linux system as the root user. To do so is considered a security risk.

Any editing tasks will refer to nano as the editor because it is simple and pre-installed, however editor any be used. Here is a reference sheet for nano.

Install and Configure Lubuntu (Raspberry Pi 2 and 3):

The current version of Ubuntu is 16.04 Xenial. There is an image which has been created specifically for the Raspberry Pi.

Note: There are issues with some versions currently available. This document uses one specific image. While other images may work, theri use is at the discretion of the user.

These instructions will be updated following the release of Ubuntu 17.04 for Raspberry Pi.

  1. Download the latest image of Lubuntu 16.04 server for the Raspberry Pi. (Lubuntu is Ubuntu with the LXDE graphical interface.)
  2. Write the image to the micro SD card using a tool appropriate to your computer operating system.
    • There are instructions for Linux, Mac OS, and Windows at the bottom of this page.
  3. Throughout the installation and configuration of the Raspberry PI, it is necessary to either establish an SSH terminal connection or have a USB keyboard and HDMI monitor connected.
    • Install an SSH client suitable for your desktop computer operating system
    • The inital boot requires a USB keyboard and HDMI monitor be connected to your Raspberry Pi to complete the initial configuration.
    • It is recommended to disable the graphical interface and use the SSH terminal method once the initial configuration is complete. The requiste steps are included in this document.
  4. Insert the SD card into the Raspberry Pi.
  5. Connect a USB keyboard, USB mouse, HDMI monitor, and a network cable if you have access to wired Ethernet.
  6. Apply power to boot the Raspberry Pi.
  7. Follow the on-screen instructions until the system displays the log-in prompt.
  8. Login with the credentials you created during the inital configuration.
  9. Enable passwordless sudo using the following command: sudo nano /etc/sudoers.d/default_user
    • Add the following text to the new file
      #user rules for ubuntu
      ubuntu ALL=(ALL) NOPASSWD:ALL
  10. Enable SSH access using the command: sudo systemctl enable ssh.service followed by the command: sudo systemctl start ssh.service
  11. Optional / Recomended / May be done at any time: Disable the LXDE graphical interface
    • Use the command: sudo systemctl disable lightdm.service.
    • Enable the boot screen output using the command: sudo nano /boot/cmdline.txt and remove the words quiet and splash
    • At anytime in the future, if you want to restore the graphical interface, use the command:sudo systemctl disable lightdm.service.. To enable it temporarily until the next reboot, use the command:sudo systemctl start lightdm.service.
  12. Setup the wireless interface using the following command: sudo nmcli device wifi connect wifi_ssid password wifi_password
    • replace wifi_ssid and wifi_password with the name and password of your local wireless router
    Alternate: The wireless may be configured using the LXDE graphical insterface.
  13. reboot the Pi using the graphical interface. If you disabled the graphical interface, then when it restarts, the graphical will not appear and you will use the terminal interface via an HDMI monitor or SSH connection.
  14. Login with the credentials you created during the inital configuration.
  15. Update the system using the command: sudo apt-get update followed by the commaond: sudo apt-get upgrade
  16. Reboot the Raspberry Pi using the command: sudo reboot
Install supporting software:

It will be necessary to have a light weight web server to support the mobile app interface. It's also a useful resource for other tasks.

  1. Update the software inventory using the command: sudo apt-get update
  2. Install the light weight web server - lighttpd - using the following command: sudo apt-get install lighttpd
    • Test the web server by opening a browser from your computer  using ng http:ip_address where ip_address is the address of the Raspberry Pi.
      • You should see a page titled "Placeholder page".
  3. Optional: Add PHP support to the web server
    • Install PHP7 using the command: sudo apt-get install php7.0-fpm php7.0
    • Edit the PHP configuration using the following command: sudo nano /etc/php/7.0/fpm/php.ini
      • Locate the line ;cgi.fix_pathinfo=1 and remove the leading semicolon (;)
    • Edit the configuration of the web server to use PHP using the following command: sudo nano /etc/lighttpd/conf-available/15-fastcgi-php.conf
      • Change the block of lines related to fastcgi.server to match the following:
        fastcgi.server += ( ".php" =>
            ((
                "socket" => "/var/run/php/php7.0-fpm.sock",
                "broken-scriptfilename" => "enable"
            ))
        )
    • Enable PHP for the web server using the commands: sudo lighttpd-enable-mod fastcgi and sudo lighttpd-enable-mod fastcgi-php
    • Restart the web server using the command: sudo /etc/init.d/lighttpd force-reload
    • Test PHP support by creating a new PHP page using the following command: sudo nano /var/www/html/info.php
      • Add the following line of code to the file: <?php phpinfo(); ?>
      • Open a browser from your computer using http:ip_address/info.php where ip_address is the address of the Raspberry Pi. You should see a page titled "PHP Version 7.x ...".
  4. Install I2C support using the command: sudo apt-get install i2c-tools
    • Test I2C support is enabled on the Raspberry Pi using the command: sudo i2cdetect -y 1
      • If an error occurs, test using the command: sudo i2cdetect -y 0
  5. Install system permissions tools using the command: sudo apt-get install daemontools
Backup the SD Card:

The SD card is now configured as a general purpose Linux server. This is a useful resource. By creating a backup - also called a clone - at this stage, the image may be used for other Pi projects. It may also be used in case it becomes necessary to start over.

It is recommended to make a backup image of the SD card periodically in case the SD card should fail or become inaccessible.

  1. Stop the Raspberry Pi using the following command: sudo shutdown now
  2. Remove the SD card from the Pi
  3. Create an image copy of the SD card (there are several internet resources explaining the procedure including this one from thePiHut).
  4. Return the SD card to the Raspberry Pi
  5. Boot the Raspberry Pi
Install ROS Base:

There are two types of ROS software that will be used on the Raspberry Pi. The first includes all of the core pages for the robot operating system.

Rather that duplicate the instructions, please refer to the ROS wiki page Ubuntu install of ROS Kinetic for the steps to install the "ROS-Base (Bare Bones)" package. After installing the ROS core, verify the setup using the first tutorial - Installing and Configuring Your ROS Environment.

Install Additional ROS Packages:

There are additional ROS packages needed in support developing the LoCoRo.

  1. Install ROSBridge using the command: sudo apt-get install ros-kinetic-rosbridge-suite
  2. Install ROS Lint using the command: sudo apt-get install ros-kinetic-roslint
Install LoCoRo specific code:

Once the ROS core has been install, it is now time to install the packages specific to the LoCoRo project. These include the I2C PWM controller package and the LoCoRo example code.

  1. Recommended: Create a new user account on GitLab (choose "register")
    • If you wish to avoid entering your GitLab username and password when using git commands, you may store them using the following command: git config credential.helper store
    • Optional: Navigate to ROS LoCoRo project and create a fork of the code. Having a fork, enables you to save your development work back to your own repository. In the step below, use the URL for your fork rather than the locoro project master URL.
  2. Change catkin workspace source directory created in the first tutorial. Use the command: cd ~/catkin_ws/src This is where all of the ROS LoCoRo project code resides.
  3. Install the I2C PWM controller package
    • Clone the ros-i2cpwmboard project from GitLab using the command: git clone https://gitlab.com/bradanlane/ros-i2cpwmboard.git
  4. Install the LoCoRo sample package
    • Clone the ros-locoro project from GitLab using the command: git clone https://gitlab.com/bradanlane/ros-locoro.git
  5. Install the tools used to automatically start the LoCoRo.
    • Clone the robot_upstart project from GitHub using the command: git clone https://github.com/clearpathrobotics/robot_upstart.git
    • For more information on robot_upstart, please refer to the online documentation.
  6. Build the workspace packages
    • Change to the catkin workspace using the command: cd ~/catkin_ws
    • Make package using the command: catkin_make
  7. Update workspace environment definitions using the command: source ~/catkin_ws/devel/setup.bash
  8. Automatically setup environment during login using the command: echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc
  9. Validate LoCoRo execution using the command: roslaunch locoro_drive locoro.launch
    • There will be some error messages because the I2C PWM board installation is completed in later instruction.
    • Look for each of the following lines within the output:
      • process[master]: started with pid [17269]
        ROS_MASTER_URI=http://localhost:11311
        process[rosout-1]: started with pid [17282]
        started core service [/rosout]
        process[i2cpwm_board_node-2]: started with pid [17285]
        process[locoro_autodrive_node-3]: started with pid [17292]
        process[locoro_servomove_node-4]: started with pid [17300]
        process[rosbridge_websocket-5]: started with pid [17302]
        process[rosapi-6]: started with pid [17303]
        [ INFO] [1484774269.909262772]: Drive mode configured: mode=mecanum, rpm=60.0000, radius=0.0620, track=0.2000, scale=1.0000
        [ INFO] [1484774269.909601424]: Servo #1 configured: position=1
        [ INFO] [1484774269.909934294]: Servo #2 configured: position=2
        [ INFO] [1484774269.910123985]: Servo #3 configured: position=3
        [ INFO] [1484774269.910703944]: Servo #4 configured: position=4
        [INFO] [1484774549.409631]: created topic: move_servo
        [INFO] [1484774549.412372]: locoro_servomove_node initialized
  10. Stop LoCoRo using the key combination: CTRL-C
  11. Create the system process which will to start the LoCoRo using the command: rosrun robot_upstart install locoro_drive/launch/locoro.launch You may manually start, stop, and get status of the LoCoRo service.
    • Check the status of the locoro service using the command: sudo systemctl status locoro.service
    • Manually stop the locoro service using the command: sudo systemctl stop locoro.service
    • Manually start the locoro service using the command: sudo systemctl start locoro.service
    • You need to stop and re-start the LoCoRo service when developing and testing new code.
  12. Recommended: repeat the backup instructions and save as a new image.
ROS Tutorials (optional):

Eventually, you will find it helpful to complete the ROS BEGINNER Level tutorials. These tutorials require a graphical desktop. If possible, use a Linux computer or a virtual machine and install ROS desktop on it. You have the option to run the ROS desktop and the tutorials on the Raspberry Pi.

An advantage of installing ROS desktop and the tutorials on your computer (or a virtual machine) will be learning ROS basics without changing your LoCoRo. Additionally, having ROS on your computer will enable you to link ROS on your computer to ROS on your LoCoRo at later stages for better experimentation. None of this is required to build and use your LoCoRo. They are of interest if you anticipate university studies in robotics or robotics as a career path.

If you choose to use the Raspberry Pi, use the following steps:

  1. Make a new backup of the SD card to preserve all of your current work
  2. Write the original backup image to the SD card
  3. Boot the backup image
  4. Re-enable the LXDE graphical interface for the Raspberry Pi using the command: sudo systemctl enable lightdm.service.
  5. Connect a USB keyboard, USB mouse, and HDMI monitor to the Raspberry Pi
  6. Reboot the Raspberry Pi using the command: sudo reboot
  7. Return to the ROS install and choose "Desktop Install" (not "Desktop-full")
  8. Proceed to work through the ROS BEGINNER Level tutorials.
  9. When complete, write the backup image from step 1 back to the SD card to restore your work

© 2017 Bradan Lane Studios | all rights reserved