Project: SimulRPi

SimulRPi is a Python library that partly fakes RPi.GPIO and simulates some I/O devices on a Raspberry Pi (RPi).

Simulating LEDs on an RPi via a terminal

Contents

1. Introduction
2. Dependencies
3. Installation instructions
4. Usage
   1. Use the library in your own code
      1. Case 1: with a try and except blocks
      2. Case 2: with a simulation flag
   2. Script run_examples
5. Example: display 3 LEDs
6. Resources
7. References

1. Introduction

In addition to partly faking RPi.GPIO, SimulRPi also simulates these I/O devices connected to an RPi:

• push buttons by listening to pressed keyboard keys and

• LEDs by blinking dots in the terminal along with their GPIO pin numbers.

When a LED is turned on, it is shown as a red dot in the terminal. The pynput package is used to monitor the keyboard for any pressed key.

Example: terminal output

Simulating LEDs on an RPi via a terminal

Each dot represents a blinking LED connected to an RPi and the number between brackets is the associated GPIO channel number. Here the LED on channel 22 toggles between on and off when a key is pressed.

Also, the color of the LEDs can be customized as you can see here where the LED on channel 22 is colored differently from the others.

2. Dependencies

• Platforms: macOS, Linux

• Python: 3.5, 3.6, 3.7, 3.8

• pynput>=1.6.8: for monitoring the keyboard for any pressed key

3. Installation instructions

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

2. Make sure to update pip:

   $ pip install --upgrade pip

   
   

3. Install the package SimulRPi with pip:

   $ pip install SimulRPi

   
   

   It will install the dependency pynput if it is not already found in your system.

4. Usage

4.1 Use the library in your own code

4.1.1 Case 1: with a try and except blocks

You can try importing RPi.GPIO first and if it is not found, then fallback on the SimulRPi.GPIO module.

try:
    import RPi.GPIO as GPIO
except ImportError:
    import SimulRPi.GPIO as GPIO

# Rest of your code
        

The code from the previous example would be put at the beginning of your file with the other imports.

4.1.2 Case 2: with a simulation flag

Or maybe you have a flag to tell whether you want to work with the simulation module or the real one.

if simulation:
    import SimulRPi.GPIO as GPIO
else:
    import RPi.GPIO as GPIO

# Rest of your code
        

4.2 Script run_examples

The run_examples script which you have access to once you install the SimulRPi package allows you to run different code examples on your RPi or computer. If it is run on your computer, it will make use of the SimulRPi.GPIO module which partly fakes RPi.GPIO.

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

$ run_examples -h

Let's run the code example 5 which blinks a LED if a specified key is pressed:

$ -s -e 5 -l 22 -t 5 -k ctrl_r

Explanation of the previous command-line:

• -s: we run the code example as a simulation, i.e. on our computer instead of an RPi
• -e 5: we run code example 5 which blinks a LED if a key is pressed
• -l 22: we blink a LED on channel 22
• - t 5: we blink a LED for a total of 5 seconds
• -k ctrl_r: a LED is blinked if the key ctrl_r is pressed

Output:

5. Example: display 3 LEDs

This example consists in displaying three LEDs on channels 9, 10, and 11, respectively. Here is the code along with the output from the terminal:

import SimulRPi.GPIO as GPIO

led_channels = [9, 10, 11]
GPIO.setmode(GPIO.BCM)
GPIO.setup(led_channels, GPIO.OUT)
GPIO.output(led_channels, GPIO.HIGH)
GPIO.cleanup()
        

6. Resources

• SimulRPi documentation

• SimulRPi Changelog

• SimulRPi GitHub: source code

• SimulRPi PyPI

• Darth-Vader-RPi: personal project using RPi.GPIO for activating a Darth Vader action figure with light and sounds and SimulRPi.GPIO as fallback if testing on a computer when no RPi is available

7. References

• pynput: a package to control and monitor input devices.

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