.. _getting-started-label: Getting Started =============== Here is everything you should need to get yourself moving with development on the RPiSoC through the Raspberry Pi! .. _getting-started-rpisoc: Using the RPiSoC ++++++++++++++++ If you're new to the RPiSoC, it would greatly benefit you to read through `its documentation `_ before going any further. :Note: Pay special attention to the sections discussing how to download a program to the board using the Bootloader Host Tool. However, if you do not intend to make modifications to the API, you do not need to reprogram the device. Program your RPiSoC +++++++++++++++++++ Once you know how to program the RPiSoC, if you need to redownload the API, or if you intend to make firmware changes (as required for :ref:`getting-started-mods`) Just `download the PSoC Creator project from git `_, make your changes if desired, and download it to the RPiSoC using the Bootloader host tool. .. _getting-started-rpi: Using the RPiSoC with the Raspberry Pi ++++++++++++++++++++++++++++++++++++++ The following is necessary set up the RPiSoC in the Raspberry Pi environment .. _getting-started-source: Download the Python source -------------------------- This can be achieved using the source hosted on our github, or by using the simplified pip process. Note that you should download the github content anyway if you intend to try the example projects Installation using pip ********************** Installing packages using pip is a convenient way to manage package updates, so this is the suggested method. But, you should still download the github content without installing it if you intend to make use of the examples. First, make sure that pip is installed. From the terminal window:: sudo apt-get install python-setuptools sudo easy_install pip Then, simply install the rpisoc source using pip:: sudo pip install rpisoc Installation using Git ********************** First, be sure that you have git installed on your Raspberry Pi. From the Terminal window:: sudo apt-get install git-core Then clone our git repo to the directory of your choice:: git clone git://github.com/EmbeditElectronics/psoc_2_pi.git Navigate to the Python folder and install the source:: cd API_Python sudo python setup.py install .. _getting-started-spi: Configure SPI and download spidev --------------------------------- Now, if you want to use all of the API on the Raspberry Pi, you will need to have the SPI bus enabled, and you will need to have the spidev libraries installed and in your working directory. Luckily, this is a very easy process. First though, you will should do an update/upgrade on your pi. Open a new terminal window and enter the following commands:: sudo apt-get clean sudo apt-get update sudo apt-get upgrade sudo reboot Next, you will need to install the python-dev libraries, if they aren't already installed:: sudo apt-get install python-dev Now you need to enable the SPI bus on your Pi, which is disabled by default to speed up the boot process:: sudo nano /etc/modprobe.d/raspi-blacklist.conf This will bring up a text editor where you will find a line that reads:: blacklist spi-bcm2708 Simply comment this line out by adding a :code:`#` to the front of it, and reboot your pi:: sudo reboot Now, make a new directory for the spidev installation, and download the source and perform the installation:: mkdir python-spi cd python-spi wget https://raw.github.com/doceme/py-spidev/master/setup.py wget https://raw.github.com/doceme/py-spidev/master/spidev_module.c sudo python setup.py install .. _getting-started-i2c: Configure I2C and download smbus -------------------------------- To use I2C for your communications between RPi and RPiSoC, you will need to configure your i2c bus, similarly to how it was done for SPI. Assuming you have done an update/upgrade recently, as you should have if you followed the previous step, you must now enable i2c. As was the case with SPI, I2C is disabled by the Pi by default. To change this, you must modify the blacklist again:: sudo nano /etc/modprobe.d/raspi-blacklist.conf Now change the line:: blacklist i2c-bcm2708 so that it instead reads:: #blacklist i2c-bcm2708 Now you need to add the I2C module to the kernel:: sudo nano /etc/modules And you should add to the end of this file the following line:: i2c-dev Now you simply must install the needed packages:: sudo apt-get install i2c-tools sudo apt-get install python-smbus And to configure the software, you must add your username to the I2C access group. In this case I'll assume your username is *pi* so:: sudo adduser pi i2c Now reboot:: sudo reboot And when the pi boots back up, open the terminal, connect the RPiSoC with the program loaded, and test the i2c bus:: i2cdetect -y 1 This should display dashed lines where no address was identified, except for where it found an address, and this should read *08* in the case of the RPiSoC API. If you do not see any results, try:: i2cdetect -y 0 And if you see the 8, make sure to modify :meth:`__init__` of :class:`rpisoc.I2C` so that it reflects the usage of the correct bus. If in either case you find that the address 0x3b is being used, and reflected by the appearance of *UU*, then try adding one of these three lines to your blacklist:: blacklist snd_soc_wm8804 blacklist snd_soc_bcm2708_i2s blacklist snd_soc_pcm512x This will disable the pi's native audio driver, i2s support, and the stereo DAC driver, in that order, but it is likely that blacklisting one of them will fix the problem. The final thing to change is the baudrate of the pi's I2C driver. I found that its default value was slightly error prone, and so I increased it, which resulted in error free results. To do this, you will need to create a config file in the modprobe.d folder; I called mine i2cbaud.conf. To create this file, simply enter into the terminal:: sudo nano /etc/modprobe.d/i2cbaud.conf and add this single line to it from your text editor:: options i2c_bcm2708 baudrate=500000 Now just reboot:: sudo reboot .. _getting-started-computer: Using the RPiSoC with your computer! ++++++++++++++++++++++++++++++++++++ To use the RPiSoC on your PC, you will need to have the RPiSoC device driver installer, you will need python 2.7 installed, your system will need to have python added to its environmental variables, and you will need to download a couple of Python packages, specifically pyserial and the rpisoc package. :Note: This has only been tested for Windows 7, Windows 8, and Ubuntu. Theoretically everything should work on OS X, but this has not yet been tested and there are no installation instructions Windows Installation -------------------- This will cover installation procedures for Windows 7 and Windows 8 Installing the RPiSoC device driver *********************************** The details of this step will depend on your Operating System. The driver which ultimately must be installed is `this one `_ :Windows 7: When you connect your RPiSoC to a USB port on your PC, it will try to find a driver to install. Of course, it will fail because you need to manually provide it the driver. - Open your Device Manager - In "Other Devices" you should see *RPiSoC* with an exclamation sign next to it, indicating that it is an unknown device - Right click on *RPiSoC* and choose **Properties** - On the *General* tab, there should be an option for **Update Driver...** If this option is not available, disconnect and reconnect the device. - Click **Update Driver...** - Choose **Browse my computer for driver software** - Now, simply provide the address bar with the folder that contains the driver linked above - If the driver cannot be found, make sure that the driver is saved as a .inf - Once the driver is found, it might warn you that the driver cannot be verified. Simply choose to install the driver anyway if this happens :Windows 8: The process should be the same as above, except you might have a problem if the driver isn't being recognized correctly as signed. If this happens, simply disable driver signature verification so that you are able to install unsigned drivers. This will require a couple of restarts. A good guide on this procedure is shown `in this SparkFun tutorial `_ With the driver successfully installed on your system as *Cypress USB UART* you can move onto the next step Installing Python ***************** On OS X and Linux, Python comes preinstalled. For Windows it does not, and so it must be downloaded and installed. - Navigate to the `release page for Python 2.7.8 `_ and scroll down to the **Download** section - Choose the appropriate installer for your Operating system. * For 32 bit Windows systems choose *Windows x86 MSI Installer (2.7.8)* * For 64 bit Windows systems choose *Windows X86-64 MSI Installer (2.7.8)* - During installation, make sure Python is installed to :code:`C:\Python27` Edit Windows path variables to include Python ********************************************* This step will allow you to call python and any packages you might have installed without having to explicitly provide their paths. This process will be slightly different between Windows 7 and 8 :Windows 7: - Right click on **Computer** and select **Properties** :Windows 8: - Press **Windows key + C** to bring up your charms panel. - Navigate to *Settings* and then *Control Panel* - Then, select *Systems and Security* then *System* From here, the steps are identical. - To the left, there will be a toolbar called *Control Panel Home* * In this toolbar, select **Advanced system settings** - In the *Advanced* tab, select **Environmental Variables...** - In the console window on the bottom, labeled *System variables*, scroll to the variable **PATH** and select **Edit** - In the *Variable value* window, scroll to the very end and enter the following text exactly :code:`;C:\Python27;C:\Python27\Scripts` To test this, restart your computer, then open the windows command prompt, and type :code:`python`. If everything so far has been successful, this will launch the python interpreter in your console window. Install required packages ************************* For your PC, there is only one third party package apart from our own that is required- pyserial. You must install this and the rpisoc package to use the API. The installer for each package can be found on our respective PyPi pages. :PySerial: - `pyserial PyPi page `_ - From that page, download and run *pyserial-2.7.win32.exe (md5)* - Run the .exe when it finishes downloading and follow the on-screen instructions to install pyserial :RPiSoC: - `rpisoc PyPi page `_ - From that page, download and run *RPiSoC-1.2.5.win32.exe (md5)* if you are using the 32-bit Python installation, or *RPiSoC-1.2.5.win-amd64.exe (md5)* if you are using the 64-bit installation - Run the .exe when it finishes downloading and follow the on-screen instructions to install the rpisoc package :Note: If in either case there is a problem with the installer (such as it being unable to locate your python installation), use pip to install the packages instead. To install the packages using pip, open the command prompt and enter the following commands:: easy_install pip pip install pyserial pip install rpisoc Linux Installation ------------------ Since the Raspberry Pi itself runs a Linux distribution, the installation process should be identical. Refer to :ref:`getting-started-source` for instructions. Using the API ------------- Of course, you will need to download an appropriate IDE to begin writing your python scripts, but which one you use is up to you. The only difference between this code and your Raspberry Pi code will be in the construction of the :class:`rpisoc.RPiSoC` object. Here, the following two lines should always be at the top of your scripts:: from rpisoc import * RPiSoC('SERIAL', DEBUG = True) To test that everything is working: - Plug your RPiSoC into your PC using a USB cable - Run any of `these scripts `_ * To run any script, either open it using python (double clicking it will work if it opens using python by default), or navigate to the directory containing the script with you command prompt and enter :code:`python script_name.py`. So to run *blinky.py* from the examples, navigate to the *examples* folder in your command prompt and enter :code:`python blinky.py` into the console .. _getting-started-mods: Changing communication protocol used by the API +++++++++++++++++++++++++++++++++++++++++++++++ By default, the API uses Serial since it can be used on both PC and the Pi. But to change this to SPI or I2C (which can only be used on the Raspberry Pi of course), it is designed to be very simple, so don't fret! On the Python Side, simply change your initialization of the RPiSoC object from:: RPiSoC('SERIAL') so that it instead reads:: RPiSoC('SPI') or:: RPiSoC('I2C') Now, in the PSoC Creator program navigate to *mem1.h* and you will find three lines that look like this: .. code-block:: c //#define USE_SPI // KEEP THIS UNCOMMENTED TO USE SPI -- COMMENT THE OTHER PROTOCOLS!! //#define USE_I2C // KEEP THIS UNCOMMENTED TO USE I2C -- COMMENT THE OTHER PROTOCOLS!! #define USE_SERIAL // KEEP THIS UNCOMMENTED TO USE SERIAL -- COMMENT THE OTHER PROTOCOLS!! This of course indicates that Serial is to be used. To change this, simply change which protocols are commented out. For instance, to change to SPI, you would replace those lines with: .. code-block:: c #define USE_SPI // KEEP THIS UNCOMMENTED TO USE SPI -- COMMENT THE OTHER PROTOCOLS!! //#define USE_I2C // KEEP THIS UNCOMMENTED TO USE I2C -- COMMENT THE OTHER PROTOCOLS!! //#define USE_SERIAL // KEEP THIS UNCOMMENTED TO USE SERIAL -- COMMENT THE OTHER PROTOCOLS!! Now, the firmware will compile itself so that SPI will be used. And for SPI, this is all that needs to be done. For I2C, there is an additional step. Including all communication protocols was a waste of resources, so I2C was left out in place of including additional features. This means to use it, you must add the component back to your schematic file, and recompile the program. To do this: - Navigate to the *.cysch* page of your workspace, and go to the *COMMUNICATION* tab - Here delete the SPI component, and replace it with either the I2C component. - Make sure to choose *I2C Slave (UDB) v3.30*, and be sure to delete the *RST_1* pin, and wire it to a *Logic Low 0* component instead. - Navigate to your design wide resources page (*.cydwr*) to give pin assignments to your new pins * Assign *SDA_1* to P1[6] * Assign *SCL_1* to P1[7] Now just compile the program, and redownload it to the RPiSoC using the Bootloader Host Tool. For more information on this step, be sure to review :ref:`getting-started-rpisoc` If you decide that you would like to revert back to SPI. You can of course just redownload the source code from our github and compile that, or you can add the component back in manually. To do this: - Once again, navigate to the *.cysch* file and the *COMMUNICATION* page - From the component catalog, choose *SPI Slave Full Duplex mode Macro v2.60* and drag the component into your design - Assign your new pins to their required locations * Assign *MISO_1* to P1[3] * Assign *MOSI_1* to P1[4] * Assign *SCLK_1* to P1[1]