Python 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 Python LoCoRo. If you want to create a ROS LoCoRo system, use the ROS SD Card documentation

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 and uses Raspbian, the official operating system from the Raspberry Pi organization.

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

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

The current version of Raspbian is 2017-03-02. There are two versions available - one with a graphical interface and one without. The PIXEL image contains a full desktop graphical environment. The PIXEL image is the recommended choice for users new to working with the Raspberry Pi and who have access to an HDMI monitor, keyboard, and mouse. Using PIXEL simplifies setting up the wireless networking and completing the LoCoRo software installation.

The Lite image contains no desktop environment. It is intended for users connecting with an SSH terminal program.

The LoCoRo SD Card instructions assume a new user with access to an HDMI monitor and USB keyboard and mouse.

If you prefer to use the the Lite image and access with SSH, there are instructions on the Raspberry Pi website.

For new users, it's recommended to read through the official documentation from Raspberry Pi Organization.

  1. Download the latest PIXEL image of Raspbian for the Raspberry Pi.
  2. Insert the SD card into the Raspberry Pi.
  3. Connect a USB keyboard, USB mouse, HDMI monitor, and a network cable if you have access to wired Ethernet.
  4. Apply power to boot the Raspberry Pi.
    • PIXEL will display a desktop environment with a control bar at the top.
    • PIXEL will automatically log in. The default user name is pi and the default password is raspberry
    • The circular raspberry icon will open a menu of installed applications and utilities.
    • The power shutdown icon is located under the applications menu.
    • The blue circle globe icon is the Chromium browser.
    • The grey window icon will open a terminal window.
    • The blue up/down arrows icon is used to configure networking.
  5. Open a terminal window
  6. Confirm PIXEL has correctly detected your keyboard by typing the ~ and then deleting it with the Backspace key. If necessary you can change the keyboard layout in the next step.
  7. Enter the command sudo raspi-config to access some basic settings. You must enable the I2C interface (one of the Interface Options). Other settings you may want to change include the user password, the hostname of the Raspberry Pi, enable SSH, or enable a Raspberry Pi camera. This is also when you can change the assigned keyboard layout. After making any changes, accept the option to reboot the Raspberry Pi. Note: Any of these settings may be changed latter using the same command.
  8. Setup access to a wireless network using the networking icon from the tool bar.
Install Python LoCoRo code:

Once the Raspbian with PIXEL 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. The WebApp will uses a Python packaged called tornado. Install this package using the command: sudo pip3 install tornado
  2. 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 Python 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.
  3. Open a terminal window. You can insure you are in home folder using the command cd ~
  4. Install the Python I2C PWM controller package
    • Start in the home folder using the command: cd ~
    • Clone the Python LoCoRo project from GitLab using the command: git clone substitude the URL of your forked project if created above
    • Change to the folder with the driver code using the command cd ~/py-i2cpwmboard/src
    • Install the driver code using the command sudo python3 install
    • Documentation for the Python LoCoRo driver code is located on the project page.
  5. Install the Python LoCoRo example code
    • Start in the home folder using the command: cd ~
    • Clone the Python LoCoRo project from GitLab using the command: git clone substitude the URL of your forked project if created above
    • Documentation for the examples are located on the project page.
  6. Install the system service to automatically start the LoCoRo when the Raspberry Pi starts.
    • Open a terminal window
    • Change to the autostart folder using the command: cd ~/py-locoro/autostart
    • install the system service using the command: ./
      • Use the command: sudo systemctl start locoro.service to manually start the service
      • Use the command: sudo systemctl status locoro.service to check the status of the service
      • Use the command: sudo systemctl stop locoro.service to manually stop the service
      • Use the command: ./ to remove the system service
    • The default program is a placeholder.
      • Once you have developed your robot program, copy it to the ~/py-locoro/autostart folder an rename it to
      • If you want to start driving the LoCoRo right away, copy the examples/ program over the
      • Use the command: sudo systemctl start locoro.service to manually start the service which will run autostart/
      It will automatically start when the Raspberry Pi starts. If you make changes to the file, remember to stop the service and then start it again to run the new changes.
  7. If you have already completed the Electronics Assembly and Hardware Assembly instructions, you may test your LoCoRo with one of the example programs located in the ~/py-locoro/examples folder. Start with the calibration example:
    • Open a terminal window
    • Change to the examples folder using the command cd ~/py-locoro/examples
    • Start the calibrate demo using the command python3
    • Follow the on-screen instructions.
    • Write down the values for center and travel for each servo number. You will need these to update the config_servo() code in the examples to match your specific hardware.
Backup the SD Card:

The SD card is now setup for your LoCoRo. By creating a backup, you have a image file 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. It's also an easy way to setup several LoCoRos!

  1. Shut down the Raspberry Pi using Applications -> shutdown menu command.
  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

If you have finished the electronics assembly, the hardware assembly, and the software installation, you have a working LoCoRo and can drive it right now!

You will want to calibrate your the servos on the LoCoRo but the defaults are likely good enough to try driving it around.

  1. From the PIXEL Application menu, choose Programming and then Python 3 (IDLE). This starts the Python development and learning environment.
  2. Click on the File menu, open the py-locoro folder and the examples folder to then open the file.
  3. Click on Run and Run Module (or press F5>. This will start the LoCoRo web server program.
    • The Python Shell window should display a message: INFO:root:Serving HTTP on port 8888
  4. Click on the Networking / Wireless icon in the PIXEL toolbar to find the IP address of the Raspberry Pi wireless.
  5. From your smartphone or tablet - connected to teh same network - open a browser using the IP address of the Raspberry Pi wireless and the port '8888'. The URL in your mobile browser will look something like:
    • You should see the webapp game controller on the mobile browser screen.
    • The joystick controls driving!

You are now ready to start programming the LoCoRo!

© 2017 Bradan Lane Studios | all rights reserved