Editing RaspberryPi:ProgrammingInPython

[[Category:RaspberryPi]]
= Overview =
Most of the content in the guide comes from the documentation, available online [https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/ here].

Python, while not as powerful as C or C++, is quickly becoming a common choice for embedded systems developers due to its ease of use and rapid development times. See [https://spectrum.ieee.org/at-work/innovation/the-2018-top-programming-languages this IEEE article]. For information on programming in C or C++, go to [[RaspberryPi:ProgrammingInC]].

This chapter serves as a short guide for programming in Python on the RPi. You will also find some templates for techniques such as debouncing, or making use of the Raspberry Pi’s multicore architecture by implementing threading.

= The RPI.GPIO Library =

The RPi.GPIO library is the common Python library used on the Raspberry Pi. Documentation for the library can be found here:<br />
https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/

It is included in the environment variables by default, so to use it, you can simply just import it into your Python script:

<syntaxhighlight lang="python">import RPi.GPIO as GPIO</syntaxhighlight>
You need to specify which board mode you’re using. For more information on board modes, see Section [[RaspberryPi:Overview#GPIO_Pins]]. Board modes are specified as follows:

<syntaxhighlight lang="python">GPIO.setmode(GPIO.BOARD)
# or
GPIO.setmode(GPIO.BCM)</syntaxhighlight>
You also need to perform “cleanup” on GPIOs when your application exists. By performing cleanup and resetting all pins to their default modes, you can prevent possible damage to your Raspberry Pi. The cleanup function is called as follows:

<syntaxhighlight lang="python">GPIO.cleanup()</syntaxhighlight>
If your program is meant to run indefinitely, and only close upon an exception, you can wrap it in a try catch, as follows:

<syntaxhighlight lang="python">if __name__ == "__main__":
    # Make sure the GPIO is stopped correctly
    try:
        while True:
            main()
    except KeyboardInterrupt:
        print("Exiting gracefully")
        GPIO.cleanup()
    except e:
        print("Some other error occurred: {}".format(e.message)})
        GPIO.cleanup()</syntaxhighlight>

= Basic IO =

Read the documentation, available [https://sourceforge.net/p/raspberry-gpio-python/wiki/Outputs/ here].

== Digital Logic ==

Digital output on the Raspberry Pi is accomplished by writing values to channels. A channel is a pin, which is numbered in the way you’ve configured. Basic configuration of a pin for output is as follows:

<syntaxhighlight lang="python">GPIO.output(<channel>, <Logic>)</syntaxhighlight>
Your logic (high, 3.3V, or low, 0V), can be specified as follows:

<ul>
<li><p>For 3.3V (high) output:</p>
<syntaxhighlight lang="python">
GPIO.output(<channel>, GPIO.HIGH)
GPIO.output(<channel>, 1)
GPIO.output(<channel>, True)
</syntaxhighlight></li>

<li><p>For 0V (low) output:</p>
<syntaxhighlight lang="python">
GPIO.output(<channel>, GPIO.LOW)
GPIO.output(<channel>, 0)
GPIO.output(<channel>, False)
</syntaxhighlight></li></ul>

Channels can also be specified in lists, for example:

<syntaxhighlight lang="python">LEDs = (11,12)
GPIO.output(LEDs, GPIO.HIGH) # Will turn all channels HIGH
GPIO.output(LEDs, (GPIO.HIGH, GPIO.LOW)) # Will the first channel HIGH, and the second LOW</syntaxhighlight>

Note that you can also read the state of the pin/channel that is set as an output by using the <code>input()</code> function. For example, if you wanted to toggle pin 12, you could do something as follows:

<syntaxhighlight lang="python">GPIO.output(12, not GPIO.input(12))</syntaxhighlight>

== Analog ==

The Raspberry Pi does not have any analog input pins. You will need to use something like the [https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf MCP3008] to read analog voltages.

== Inputs ==

=== Digital Read ===

To read the value of a digital pin, you can use the <code>input()</code> function:

<syntaxhighlight lang="python">if GPIO.input(12):
    print("Pin 12 HIGH")
else:
    print("Pin 12 LOW")</syntaxhighlight>
=== Pull Up/Pull Down Resistors ===

Using pull up and pull down resistors is essential when working with digital logic. Thankfully, the Raspberry Pi has internal pull up and pull down resistors. To make use of these, initialize the pin/channel as follows:

<syntaxhighlight lang="python">GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_UP)
# or
GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_DOWN)</syntaxhighlight>
=== Interrupts ===

Very often it is useful to set up an interrupt, for example to trigger an event when a button is pressed. Callback functions are executed on a different thread. If you have multiple callbacks, know that they will be executed sequentially as only one thread exists for interrupts. Interrupts can be implemented as follows:

<syntaxhighlight lang="python"># The bounce time is given in milliseconds.
# If your pin is set to use pull down resistors
# Connect a button between <channel> and 3.3V
GPIO.add_event_detect(<channel>, GPIO.RISING, callback=callback_method(), bouncetime=200)
# If your pin is set to use pull up resistors
# Connect a button between <channel> and GND
GPIO.add_event_detect(<channel>, GPIO.FALLING, callback=callback_method(), bouncetime=200)  </syntaxhighlight>
=== Other functions ===

The RPi.GPIO Library offers other functions for interrupts the first is the <code>wait_for_edge()</code> function, which is designed to block execution until an edge is detected. You can detect edges of <code>GPIO.RISING</code>, <code>GPIO.FALLING</code>, or <code>GPIO.BOTH</code>. The timeout is given in milliseconds:

<syntaxhighlight lang="python"># wait for up to 5 seconds for a rising edge
edge = GPIO.wait_for_edge(<channel>, GPIO_RISING, timeout=5000)
if edge is None:
    print('Timeout occurred')
else:
    print('Edge detected on pin <CHANNEL>')</syntaxhighlight>

Another function is the <code>event_detected()</code> function. From the docs: “The event_detected() function is designed to be used in a loop with other things, but unlike polling it is not going to miss the change in state of an input while the CPU is busy working on other things. This could be useful when using something like Pygame or PyQt where there is a main loop listening and responding to GUI events in a timely basis.”

<syntaxhighlight lang="python">GPIO.add_event_detect(channel, GPIO.RISING)  # add rising edge detection on a channel
if GPIO.event_detected(channel):
    print('Button pressed')</syntaxhighlight>

= Communication Protocols =

The RPi.GPIO library has no native support for communication protocols. Very often, specific Python libraries are provided on a per-device use case. However, this can become tedious and cause your code to become bloated. See the sections below for relevant libraries for using I2C and SPI directly.

== I2C ==

Ensure you enable I2C in <code>raspi-config</code>.

To use I2C in Python, you can use the <code>smbus</code> library. To do this, we need to install and configure smbus. This is usually done by default, but instructions are included for posterity.

<pre>$ sudo apt-get install i2c-tools
$ sudo apt-get install python-smbus
$ sudo adduser &lt;username&gt; i2c
$ sudo reboot</pre>
Once you connect a device, you can run <code>$gpio i2cdetect</code> to determine if a device is detected on the I2C bus. In the example below, there is an electronic compass (GY-271) connected to the Pi.

[[File:I2cdetect.png|frame|none|alt=|An i2cdetect example]]

To initialize an I2C device, do the following:

<pre>import smbus
i2cdevice = smbus.SMBus(1) # 1 indicates /dev/i2c-1
address = 0x1e #whatever the device is for your i2c device</pre>
To read a byte from the I2C device:

<pre>result = i2cdevice.read_byte_data(address, &lt;register&gt;)</pre>
To write a byte to the I2C device:

<pre>i2cdevice.write_byte_data(address, &lt;register&gt;, &lt;value&gt;)</pre>
=== Methods Available ===

<code>smbus</code> has multiple methods. The documentation for these is quite minimal, but brief descriptions are available [http://wiki.erazor-zone.de/wiki:linux:python:smbus:doc here].

Note: If you're working with EEPROM (specifically 24C32), you may need to read the answer to the questions given [https://www.raspberrypi.org/forums/viewtopic.php?p=1401819&sid=582cace49dad59d93f4e0369047dd89d#p1401819 here].

== SPI ==

Ensure you enable SPI in <code>raspi-config</code>.

You can use SPI in Python by using the <code>spidev</code> library. Documentation is available [https://pypi.org/project/spidev/ here]. Basic usage is as follows:

<pre>import spidev

#Bus is 0 or 1, depending on which SPI bus you've connected to
bus = 0
#Device is the chip select pin. Set to 0 or 1, depending on the connections
device = 1

spi = spidev.SpiDev() #Enable SPI
spi.open(bus, device) #Open connection to a specific bus and device (CS pin)

# Set settings (SPI speed and mode)
spi.max_speed_hz = 500000
spi.mode = 0

to_send = [0x01, 0x02, 0x03] #define what to send
spi.xfer(to_send)

# Close the SPI connection
close()</pre>
=== Settings ===

The following settings are configurable in the <code>spidev</code> library, and can be set as follows:

<pre>spi = spidev.SpiDev() #Enable SPI
spi.&lt;setting&gt; = &lt;value&gt;</pre>
List of settings:

* <code>bits_per_word</code>
* <code>cs_high</code>
* <code>loop</code><br />
Set the “SPI_LOOP” flag to enable loopback mode
* <code>no_cs</code><br />
Set the “SPI_NO_CS” flag to disable use of the chip select (although the driver may still own the CS pin)
* <code>lsbfirst</code>
* <code>max_speed_hz</code>
* <code>mode</code><br />
SPI mode as two bit pattern of clock polarity and phase [CPOL/CPHA], min: 0b00 = 0, max: 0b11 = 3
* <code>threewire</code><br />
SI/SO signals shared

=== Methods ===

The following methods are available in the <code>spidev</code> library

<ul>

<li><code>open(bus, device)</code><br>
Connects to the specified SPI device, opening <code>/dev/spidev&lt;bus&gt;.&lt;device&gt;</code>
</li>
<li><code>readbytes(n)</code><br>
Read n bytes from SPI device.
</li>
<li><code>writebytes(list of values)</code><br />
Writes a list of values to SPI device.
</li>
<li> <code>writebytes2(list of values)</code><br />
Similar to ‘writebytes‘ but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations. Also, writebytes2 understands [https://docs.python.org/3/c-api/buffer.html buffer protocol] so it can accept numpy byte arrays for example without need to convert them with <code>tolist()</code> first. This offers much better performance where you need to transfer frames to SPI-connected displays for instance.
</li>
<li><code>xfer(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be released and reactivated between blocks. Delay specifies the delay in usec between blocks.
</li>
<li><code>xfer2(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be held active between blocks.
</li>
<li><code>xfer3(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Similar to xfer2 but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations.
</li>
<li><code>close()</code><br />
Disconnects from the SPI device.
</li>
</ul>

= Using Threads =

[https://realpython.com/intro-to-python-threading/ This guide] serves as the basis for the text below. This manual does not teach everything there is to know about threading in Python, but will give you the basics to be able to utilize threads for simple tasks that may be of use to you in the practicals. It’s strongly recommended you read through that text if you have not yet been exposed to threading concepts.

This text does not cover issues and precautions when working with threads, such as mutex’s and locks, data races, producer/consumer concerns and the likes. However, these are knowledge areas of critical importance, and it is strongly suggested that the reader tries to make an effort to understand these concerns before writing threaded code.

== The Threading Library ==

The Python library <code>threading</code> library offers all the functionality one would expect. Import it in to your code in the standard way:

<pre>import threading</pre>
There are 4 basic things you need to do when creating a thread:

# Initialize it
# Start it
# Let is execute
# “Shut it down” by joining

== Basic Thread Usage ==

For example, if you want to create a separate thread to fetch a sensor value five times, you could do it as follows:

<pre>import threading
import time
import RPi.GPIO as GPIO

def setup():
    #Contains all code for initialisation of RPi.GPIO

def fetch_sensor_vals(sensor_pin):
    for i in range(5):
        GPIO.input(sensor_pin)
        time.sleep(2)
    
if __name__ == &quot;__main__&quot;:
    setup()
    # Create a thread to call the function and pass &quot;12&quot; in as sensor pin
    x = threading.Thread(target=fetch_sensor_vals, args=(12,)) 
    print(&quot;Starting thread&quot;)
    x.start()
    print(&quot;Waiting for the thread to finish&quot;)
    x.join()
    print(&quot;Reading finished&quot;)</pre>
== Timed Thread Usage ==

Often in embedded systems we want a specific task to run every X time units. There is an option in the Python threading library. It works as follows:

<syntaxhighlight lang="python" line='line'>import threading
import datetime

def print_time_thread():
    """
    This function prints the time to the screen every five seconds
    """
    thread = threading.Timer(5.0, print_time_thread)
    thread.daemon = True  # Daemon threads exit when the program does
    thread.start()
    print(datetime.datetime.now())
    

if __name__ == "__main__":
    print_time_thread() # call it once to start the thread
    
    # Tell our program to run indefinitely
    while True:
        pass

</syntaxhighlight>

You will see that in this code example, we have also set the <code>daemon</code> flag of the thread to be be <code>True</code>. A daemon thread will shut down immediately when the program exits. In essence, the daemon thread will run indefinitely in the background until your application exits, and you do not need to worry about calling <code>join()</code>.<ref>It’s important to note that calling t.join() will wait for a thread to finish executing, even if it is a daemon.
</ref>