Prerequisite¶

This Tutorial assume that

• You can read this ;)
• You can spell "Box0" correctly. ==> say: box zero
• You are familiar with Python [1]
• You have a Box0 and basic electronics components

[1]: Python is used as the programming language for the tutorial. If you like you can use libbox0 Julia Binding, Java Binding, or with C++, C.

Introduction¶

Box0 devices can be controlled using Python.
There is a module called "box0" for python.

module can be imported in python by using

import box0

Opening Device¶

In order to do anything with the device, user need to open a device.
A box0.Device crossponds to a physical Hardware.

you can open a device using box0.usb.open_supported().
box0.usb.open_supported() means "Open a supported Box0 device connected on USB"

import box0
dev = box0.usb.open_supported()

Opening Module¶

Device is itself not useful for anything.
In order to do something useful out of device, we need to take a module from it and work with it.

You can consider Device as House but a House contain Rooms where you live.
In Box0, all modules are independent of each other.
So, if you have a module, it is expected not to be affected by any other module.

A device can contain many types of module.
you can open open module using <device>.<module>()

[1]: We need "Electronic rights"!

Resource Disposal¶

If you have allocated a Device or Module, you need to dispose it properly. The problem become promintent in Jupyter or IPython because the same kernel for execution (until the "Kernel reset" is performed) So, if you have allocated a module, need to deallocate it after use.

You can use various techniques, some are given below.

1. Use python with
   Using python with, you can allocate resource and deallocate the resource the automatically when the execution goes out of the scope of the block.
   Technical Details:
   https://www.python.org/dev/peps/pep-0343/
   https://www.python.org/dev/peps/pep-0310/

   Example:

     import box0
     with box0.usb.open_supported() as dev, dev.<module>() as mod:
         # do something with "mod"

2. Manually handling Exception
   When you press "interrupt kernel" it is converted into KeyboardInterrupt which is a exception that stop the execution of the program.
   You need to catch the exception and deallocate the resource and then exit.
   Example:

    import box0
   
    # allocate resources
    dev = box0.usb.open_supported()
    mod = dev.<module>()
   
    try:
        while True:
            # do something with "mod"
     except KeyboardInterrupt:
         # ah ha, we need to stop right now!
         pass
   
     # deallocate resources
     mod.close()
     dev.close()

If modules are not properly close (in Jupyter or IPython) the, the resources are still allocated to object that has not been closed (but not garbage collected i.e. __del__ not called).
Next time the cell is executed, the module allocation will fail with Resource not available (ResultException: B0_ERR_UNAVIL)