Introduction to pyBox0

pyBox0 is a Python binding of libbox0. libbox0 is the C library that does the communication with physical devices.

Box0 infrastructure

Importing

import box0

What is a Device

A device is an interface to the physical device you have.

A device can be acquired via multiple method, at the moment USB only.

Opening a device

import box0

dev = box0.usb.open_supported()
# ... do something with "dev"

In the above code, box0.usb.open_supported try to open any USB device connected that can be used as Box0. quick and easy!

You can do something with “dev” like

import box0

dev = box0.usb.open_supported()
print(dev.name) # Print device name (provided by device - brand)
print(dev.serial) # Print serial number (provided by device)
print(dev.manuf) # Print manufacturer name (provided by device)

What is a Module

A module is a portion of device that perform a dedicated function. A device can contain multiple modules.

Example of module with their uses.

Name of module Short name Use
Analog In AIN Read analog signal
Analog Out AOUT Generate analog signal
Digital Input/Output DIO Generate, Read digital signal
Serial Peripherial Interface SPI Communicate with SPI slaves
Inter Integerated Communication I2C Communicate with I2C slaves
Pulse Width Modulation PWM Generate Pulse Width Modulation

Opening a module

From the above, we know how to open a device. Now, we will open a module from device.

import box0

dev = box0.usb.open_supported()

my_ain = dev.ain() # Open Analog In (with index=0) from device

# .... do something with "my_ain"

The above pattern can be applied for all type of module.

Short name <method>
AIN box0.Device.ain()
AOUT box0.Device.aout()
DIO box0.Device.dio()
SPI box0.Device.spi()
I2C box0.Device.i2c()
PWM box0.Device.pwm()

You can use my_module = dev.<method>().

Exception and failure

libbox0. functions return a negative integer value (actually enum) to tell that some kind of error has occured.

pyBox0 convert these negative values to Exception with the help of a exception class box0.ResultException

import box0

try:
        dev = box0.usb.open_supported()
except ResultException, e:
        print("failed! (%s)" % e)
        # name of the exception: e.name()
        # explaination of exception: e.explain()

Resource management

Device, resource and driver are resources which are taken for a time and returned back when it is no more required.

A device, module and driver after closing cannot be used. Doing so will result in undefined behaviour. You can use close() method for closing, the del keyword leads to close() too.

You can also use with keyword for automatic disposal when execution of a block finishes. Device, module and driver support with statement.