{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using Peripherals with the Base overlay "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Base overlay\n",
    "\n",
    "The PYNQ-Z1 has 2 Pmod connectors. PMODA and PMODB as indicated below are connected to the FPGA fabric. \n",
    "\n",
    "\n",
    "![](images/pynqz1_pmod_interface.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Pmods with an overlay\n",
    "To use a peripheral two software components are required; a driver application written in C for the IOP, and a Python module. These components are provided as part of the Pynq package for supported peripherals. See the *IO Processors: Writing your own software* section of the documentation for writing drivers for your own peripherals. \n",
    "\n",
    "The Python module instantiates the peripheral, and loads the driver application to the appropriate IOP. The IOP will also be reset and start executing the new application. \n",
    "\n",
    "The Python module will send commands which the IOP will interpret and execute. The Python module may also send the data if necessary. The IOP will read from and write data into the shared memory area. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example: Using the OLED and the Ambient Light Sensor (ALS)\n",
    "\n",
    "This examples requires the PmodOLED (OLED), and PmodALS (Ambient Light Sensor). \n",
    "Plug the PmodOLED into PMODA, and PmodALS into the top row of PMODB. (Currently, the PmodALS can only be used in the top row of a Pmod port.)\n",
    "\n",
    "OLED displaying light reading from ambient light sensor:\n",
    "\n",
    "![](images/als_oled_demo.JPG)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Execute the next cell to load the FPGA fabric with the desired overlay, and then import the OLED module and instantiate it on PMODB:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from pynq import Overlay\n",
    "from pynq.iop import Pmod_OLED\n",
    "from pynq.iop import PMODB\n",
    "\n",
    "ol = Overlay(\"base.bit\")\n",
    "ol.download()\n",
    "oled = Pmod_OLED(PMODB)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Try writing a message to the OLED."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "oled.write(\"Hello World\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "oled.clear()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import the ALS library, create an instance of the ALS Pmod, and read the value from the sensor."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from pynq.iop import Pmod_ALS\n",
    "from pynq.iop import PMODA\n",
    "\n",
    "als = Pmod_ALS(PMODA)\n",
    "als.read()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Write the value from the ALS to the OLED. The ALS sensor returns an 8-bit value. \n",
    "\n",
    "* 0 : Darkest\n",
    "* 255 : Brightest"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "oled.write(\"Light value : \" + str(als.read()))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import time\n",
    "from pynq.iop import Pmod_ALS\n",
    "from pynq.iop import PMODA\n",
    "\n",
    "als = Pmod_ALS(PMODA)\n",
    "\n",
    "als.set_log_interval_ms(100)\n",
    "als.start_log()\n",
    "time.sleep(1)\n",
    "als.stop_log()\n",
    "als.get_log()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "For information on other supported peripherals and their API, see the *pynq.iop package* section of the documentation."
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Raw Cell Format",
  "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",
   "version": "3.4.3+"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}
