Beginner Guide.ipynb 5.82 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Prerequisite\n",
    "\n",
    "This Tutorial assume that\n",
    "\n",
    "- You can read this ;)\n",
    "- You can spell \"Box0\" correctly. ==>  say:  _box_ _zero_\n",
    "- You are familiar with [Python][python] [1]\n",
    "- You have a [Box0][box0] and basic electronics components\n",
    "\n",
    "[1]: [Python][python] is used as the programming language for the tutorial. If you like you can use libbox0 [Julia][julia] Binding, Java Binding, or with C++, C.\n",
    "[python]: http://www.python.org \"Python\"\n",
18
    "[box0]: http://www.madresistor.org/box0/ \"Box0\"\n",
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145
    "[julia]: http://julialang.org/ \"Julia Language\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction\n",
    "\n",
    "Box0 devices can be controlled using Python.  \n",
    "There is a module called \"box0\" for python.\n",
    "\n",
    "module can be imported in python by using \n",
    "\n",
    "    import box0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Opening Device\n",
    "In order to do anything with the device, user need to open a device.  \n",
    "A `box0.Device` crossponds to a physical Hardware.\n",
    "\n",
    "you can open a device using `box0.usb.open_supported()`.  \n",
    "`box0.usb.open_supported()` means \"Open a supported Box0 device connected on USB\"\n",
    "\n",
    "    import box0\n",
    "    dev = box0.usb.open_supported()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Opening Module\n",
    "Device is itself not useful for anything.  \n",
    "In order to do something useful out of device, we need to take a module from it and work with it.\n",
    "\n",
    "You can consider Device as _House_ but a _House_ contain _Rooms_ where you live.  \n",
    "In Box0, all modules are independent of each other.  \n",
    "So, if you have a module, it is expected not to be affected by any other module.\n",
    "\n",
    "A device can contain many types of module.  \n",
    "you can open open module using `<device>.<module>()`\n",
    "\n",
    "| Name | Description                     | Open       | Use\n",
    "|------|---------------------------------|------------|--------------------------------------------\n",
    "| AIN  | Analog In                       | dev.ain()  | Capture Analog Signal from cruel world\n",
    "| AOUT | Analog Out                      | dev.aout() | Generate Analog Signal for the cruel world\n",
    "| SPI  | Serial Peripherial Interface    | dev.spi()  | Communicate with Slaves [1] connected on [SPI][spi] Bus\n",
    "| I2C  | Inter Integerated Communication | dev.i2c()  | Communicate with Slaves [1] connected on [I2C][i2c] Bus\n",
    "| PWM  | Pulse Width Modulation          | dev.pwm()  | Generate [Pulse Width modulated signals][pwm]\n",
    "| DIO  | Digital Input/Output            | dev.dio()  | Read/Write Digital signals\n",
    "\n",
    "[spi]: https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus\n",
    "[i2c]: https://en.wikipedia.org/wiki/I%C2%B2C\n",
    "[1]: We need \"_Electronic_ rights\"!\n",
    "[pwm]: https://en.wikipedia.org/wiki/Pulse-width_modulation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Resource Disposal\n",
    "\n",
    "If you have allocated a Device or Module, you need to dispose it properly.\n",
    "The problem become promintent in Jupyter or IPython because the same kernel for execution (until the \"Kernel reset\" is performed)\n",
    "So, if you have allocated a module, need to deallocate it after use.\n",
    "\n",
    "You can use various techniques, some are given below.\n",
    "\n",
    "1. Use python `with`  \n",
    "   Using python `with`, you can allocate resource and deallocate the resource the automatically when the execution goes out of the scope of the block.  \n",
    "    Technical Details:  \n",
    "     https://www.python.org/dev/peps/pep-0343/  \n",
    "     https://www.python.org/dev/peps/pep-0310/  \n",
    "   \n",
    "    Example:\n",
    "         import box0\n",
    "         with box0.usb.open_supported() as dev, dev.<module>() as mod:\n",
    "             # do something with \"mod\"\n",
    "\n",
    "2. Manually handling Exception   \n",
    "   When you press \"interrupt kernel\" it is converted into `KeyboardInterrupt` which is a exception that stop the execution of the program.  \n",
    "   You need to catch the exception and deallocate the resource and then exit.  \n",
    "    Example:\n",
    "        import box0\n",
    "        \n",
    "        # allocate resources\n",
    "        dev = box0.usb.open_supported()\n",
    "        mod = dev.<module>()\n",
    "        \n",
    "        try:\n",
    "            while True:\n",
    "                # do something with \"mod\"\n",
    "         except KeyboardInterrupt:\n",
    "             # ah ha, we need to stop right now!\n",
    "             pass\n",
    "        \n",
    "         # deallocate resources\n",
    "         mod.close()\n",
    "         dev.close()\n",
    " \n",
    "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).  \n",
    "Next time the cell is executed, the module allocation will fail with Resource not available (ResultException: B0_ERR_UNAVIL)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
146
   "version": "3.5.2"
147 148 149 150 151
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}