README

Documentation Status Build Status

Darth-Vader-RPi (0.1.0a0.dev1) is a Python-based Raspberry Pi (RPi) project about activating a Darth Vader action figure by turning on LEDs on his suit and lightsaber, and by playing sounds such as some of his famous quotes.

Important

If you don’t have an RPi, don’t worry. You can still test the script on your own computer because the darth_vader_rpi package uses the SimulRPi library to simulate I/O devices connected to an RPi such as LEDs and push buttons by blinking red dots in the terminal and playing sounds when a keyboard key is pressed. Almost like testing with a real RPi!

Disclaimer: I also wrote the SimulRPi library

Introduction

The Darth Vader action figure is 11.5 inches tall (which is this one from Hasbro) and was modified to make it more lifelike by illuminating the lightsaber, chest control box, and belt. 3 push buttons are connected to an RPi and control the following sounds and LEDs:

  1. Some of his famous quotes

  2. The Imperial march theme song

  3. The lightsaber drawing, hum and retraction sounds

  4. The lightbsaber illumination (3 LEDs)

His iconic breathing sound plays in the background almost as soon as the RPi is run with the start_dv script.

Darth Vader action figure activated

Click on the above image for the full video to see the LEDs turning on and hear the different sounds produced by pressing the push buttons

Connection diagram

Here’s how the various LEDs and push buttons are connected to the Raspberry Pi:

  • The lightsaber is illuminated by 3 LEDs connected in parallel.

  • The Top, Middle, and Bottom LEDs illuminate the slots in Darth Vader’s chest control box. They blink in a specific sequence as specified in the configuration file.

  • When the Lightsaber button is first pressed, it produces the drawing sound, illuminates the sword, and a hum sound persists until the Lightsaber button is turned off. If the button is pressed again, it produces the sound of retracting the lightsaber and turns it off.

    NOTE: the Lightsaber button can be pressed while the Song button or the Quotes button is playing audio since they use different audio channels.

  • The Song button plays the Imperial March song by Jacob Townsend.

  • The Quotes button plays famous Darth Vader quotes when pressed. For testing purposes, the darth_vader_rpi package comes with two movie lines:

    However, you could add more quotes if you want.

Dependencies

  • Platforms: Linux, macOS

  • Python: 3.5, 3.6, 3.7, 3.8

  • Packages

    • dv_sounds>=0.1.0a0: for retrieving the sound files (quotes, songs, and sound effects)

    • pygame>=1.9.3: for playing sounds

    • pynput>=1.6.8: needed by SimulRPi for monitoring the keyboard when simulating push buttons with keyboard keys, i.e. when running the start_dv script in simulation mode

    • SimulRPi >=0.1.0a0: for partly faking RPI.GPIO and simulating I/O devices connected to an RPi such as LEDs and push buttons in case that you don’t have access to an RPi

Important

At the time of this writing (2020-08-28), I couldn’t install pygame 1.9.6 (the latest stable release) with Python 3.5 and 3.8, on macOS. However, the latest pre-release development version (2.0.0.dev10) worked well with Python 3.5 and 3.8, on macOS.

Installation instructions

  1. It is highly recommended to install darth_vader_rpi in a virtual environment using for example venv or conda.

  2. Make sure to update pip:

    $ pip install --upgrade pip
    
  3. Install the package darth_vader_rpi (released version 0.1.0a0) with pip:

    $ pip install git+https://github.com/raul23/Darth-Vader-RPi@v0.1.0a0#egg=Darth-Vader-RPi
    

    It will install the dependencies if they are not already found in your system.

Important

Make sure that pip is working with the correct Python version. It might be the case that pip is using Python 2.x You can find what Python version pip uses with the following:

$ pip -V

If pip is working with the wrong Python version, then try to use pip3 which works with Python 3.x

Note

To install the bleeding-edge version (0.1.0a0.dev1) of the darth_vader_rpi package:

$ pip install git+https://github.com/raul23/Darth-Vader-RPi#egg=Darth-Vader-RPi

However, this latest version is not as stable as the released version but you get the latest features being implemented.

Warning message

If you get the warning message from pip that the start_dv script is not defined in your PATH:

WARNING: The script start_dv is installed in '/home/pi/.local/bin' which is not on PATH.

Add the directory mentioned in the warning to your PATH by editing your configuration file (e.g. .bashrc). See this article on how to set PATH on Linux and macOS.

Test installation

  1. Test your installation by importing darth_vader_rpi and printing its version:

    $ python -c "import darth_vader_rpi; print(darth_vader_rpi.__version__)"
    
  2. You can also test that the dependencies were installed correctly:

    $ python -c "import dv_sounds, pygame, pynput, SimulRPi"
    

Usage

Script start_dv

Once the darth_vader_rpi package is installed, you should have access to the start_dv script which turns on LEDs and plays sound effects on a Raspberry Pi (RPi).

Run the script on your RPi with default values for the GPIO channels and other settings:

$ start_dv

If you want to test the script on your computer (use the -s flag for simulation):

$ start_dv -s

Note

Both previous commands will use the default values from the configuration file (e.g GPIO channel numbers, channel volume).

Check Change default settings on how to modify these values.

Important

In order to stop the start_dv script at any moment, press ctrl + c.

List of options

To display the script’s list of options and their descriptions:

$ start_dv -h
--version

show program’s version number and exit

-q, --quiet

Enable quiet mode, i.e. nothing will be printed. (default: False)

-s, --simulation

Enable simulation mode, i.e. SimulRPi.GPIO will be used for simulating RPi.GPIO. (default: False)

-v, --verbose

Print various debugging information, e.g. print traceback when there is an exception. (default: False)

Edit a configuration file:

-e cfg_name, --edit cfg_name

Edit a configuration file. Provide log_cfg for the logging config file or cfg for the main config file. (default: None)

-a APP, --app-name APP

Name of the application to use for editing the file. If no name is given, then the default application for opening this type of file will be used. (default: None)

Simulating on your computer

If you don’t have access to a Raspberry Pi (RPi) and want to try out the start_dv script, you can run it with the -s flag. It will make use of the SimulRPi library to simulate LEDs and push buttons connected to an RPi by blinking red dots in the terminal and monitoring pressed keyboard keys:

$ start_dv -s

NOTE: the last command makes use of default values. See Change default settings on how to change these values.

Here’s how the keyboard keys are related by default to push buttons connected to an RPi:

  • cmd_l —–> lightsaber button

  • alt_l —–> song button

  • alt_r —–> quotes button

Check Change keymap if you want to change this default key-to-channel mapping.

Here is a video of what it looks like in a terminal when running the start_dv script on a computer instead of an RPi:

LEDs and buttons simulation in a terminal [Darth-Vader-RPi project]

Click on the above image for the full video

How to uninstall

To uninstall only the package darth_vader_rpi:

$ pip uninstall darth_vader_rpi

To uninstall the package darth_vader_rpi and its dependencies:

$ pip uninstall darth_vader_rpi dv_sounds pygame pynput simulrpi

You can exclude from the previous command-line those dependencies that you don’t want to uninstall.

Note

When uninstalling the darth_vader_rpi package, you might be informed that the configuration files logging_cfg.json and main_cfg.json won’t be removed by pip. You can remove those files manually by noting their paths returned by pip. Or you can leave them so your saved settings can be re-used the next time you re-install the package.

Example:

$ pip uninstall darth-vader-rpi
Found existing installation: Darth-Vader-RPi 0.1.0a0
Uninstalling Darth-Vader-RPi-0.1.0a0:
  Would remove:
    /Users/test/miniconda3/envs/rpi_py37/bin/start_dv
    /Users/test/miniconda3/envs/rpi_py37/lib/python3.7/site-packages/Darth_Vader_RPi-0.1.0a0.dist-info/*
    /Users/test/miniconda3/envs/rpi_py37/lib/python3.7/site-packages/darth_vader_rpi/*
  Would not remove (might be manually added):
    /Users/test/miniconda3/envs/rpi_py37/lib/python3.7/site-packages/darth_vader_rpi/configs/logging_cfg.json
    /Users/test/miniconda3/envs/rpi_py37/lib/python3.7/site-packages/darth_vader_rpi/configs/main_cfg.json
$ rm -r /Users/test/miniconda3/envs/rpi_py37/lib/python3.7/site-packages/darth_vader_rpi

Credits

Sounds

Others

References

  • dv_sounds: a package for downloading the various sounds needed for the Darth-Vader-RPi project, e.g. ligthsaber sound effects.

  • pygame: a Python library to write multimedia software, such as games, built on top of the SDL library.

  • RPI.GPIO: a module to control RPi GPIO channels.

  • SimulRPi: a package that partly fakes RPi.GPIO and simulates some I/O devices on a Raspberry Pi. It makes use of the pynput library for monitoring the keyboard for any pressed key.