Library tutorial

Included in PyBBIO is about the simplest possible example library, found at PyBBIO/bbio/libraries/example.py, and there's a test program that demonstrates using it found at PyBBIO/tests/library_test.py. That's not very exciting though, so let's walk through a slightly more useful library.

In the spirit of Arduino, we'll use the same example they use to write our first library: Morse code.

We'll start with the same program to transmit SOS, which looks like this translated to PyBBIO (and with a few added loops):

from bbio import *

pin = USR3

def setup():
  pinMode(pin, OUTPUT)

def loop():
  for i in range(3): dot() 
  for i in range(3): dash()
  for i in range(3): dot() 
  delay(3000)

def dot():
  digitalWrite(pin, HIGH)
  delay(250)
  digitalWrite(pin, LOW)
  delay(250)

def dash():
  digitalWrite(pin, HIGH)
  delay(1000)
  digitalWrite(pin, LOW)
  delay(250)

run(setup, loop)

When run, this program will blink SOS in Morse code on the USR3 LED (next to the Ethernet jack).

At this point we have two options; we can either stick the dot() and dash() functions into a file and call it a library, or we can take the more complete and self-contained object-oriented approach. We'll start with the first:

To turn this into a library, all that is needed is to create a file in the bbio/libraries/ directory, we'll use bbio/libraries/morse_simple.py for this. It should look something like this:

from bbio import *

def dot(pin):
  digitalWrite(pin, HIGH)
  delay(250)
  digitalWrite(pin, LOW)
  delay(250)

def dash(pin):
  digitalWrite(pin, HIGH)
  delay(1000)
  digitalWrite(pin, LOW)
  delay(250)

The first thing to do in any library that uses any of PyBBIO's functions or constants is to import PyBBIO. Then we simply add our two functions. This time we need to pass the desired pin to our functions, because the pin variable does not exist within the scope of this file.

If we wanted to use this library to blink SOS on the USR3 LED again, we would write something like this:

from bbio import *
from bbio.libraries.morse_simple import dot, dash

pin = USR3

def setup():
  pinMode(pin, OUTPUT)

def loop():
  for i in range(3): dot(pin) 
  for i in range(3): dash(pin)
  for i in range(3): dot(pin) 
  delay(3000)

run(setup, loop)

Note that we import bbio before morse_simple.

Well, that gets the job done, but what if we wanted to transmit a few different messages all on different pins? We might end up with a global variable for each pin, as well as a pinMode() for each in the setup() routine. This seems a bit redundant, so it would be nice to have a "Morse code transmitter" object for each, which would set the pin direction for us. This is easily achieved with a Python class.

Before we go any further, while this library works just fine in a single file, or module, it tends to be a bit neater if bbio/libraries/ contains only directories. To do this we use what Python calls a Package. In its simplest form, a Package is just a directory containing a file called __init__.py. With this file, the directory, or Package, can be imported just as if it were a .py file, and __init__.py will be evaluated automatically. This also provides a place to put any sort of documentation or license files.

So we'll create the directory bbio/libraries/morse/, and a file in it called __init__.py. We could simply put all our code into this file, but I always like to create at least one additional file with a more descriptive name, so we'll also create the file bbio/libraries/morse/morse.py. To have this file imported with the package, we need only put a single line into __init__.py:

from morse import *

Now for morse.py. Let's recall what we want here: a standalone Morse code transmitter, which sets the direction of its dedicated pin, and has dot() and dash() methods. If you were going to be using this for real, you would probably want certain messages built in, so lets even add an sos() method. This will look something like this:

from bbio import *

class Morse:
  def __init__(self, pin):
    self.pin = pin
    pinMode(self.pin, OUTPUT)

  def dot(self):
    digitalWrite(self.pin, HIGH)
    delay(250)
    digitalWrite(self.pin, LOW)
    delay(250)

  def dash(self):
    digitalWrite(self.pin, HIGH)
    delay(1000)
    digitalWrite(self.pin, LOW)
    delay(250)

  def sos(self):
    for i in range(3): self.dot()
    for i in range(3): self.dash()
    for i in range(3): self.dot()

So once we have that all saved, let's use it to first blink SOS on the USR2 LED, then on the USR3 LED:

from bbio import *
from bbio.libraries.morse import Morse

morse1 = Morse(USR2)
morse2 = Morse(USR3)

def setup():
  pass

def loop():
  morse1.sos()
  morse2.sos()
  delay(3000)

run(setup, loop)

So we end up with a file that's about half as long as what we started with, and it's doing twice as much!