Editing Electrical Onboarding/PSoC getting started (Blink)

PSoC (Programmable System on Chip) is a powerful [https://en.wikipedia.org/wiki/Microcontroller microcontroller] platform that provides flexible hardware functionality in addition to the same software functionality you get with other micro controllers. 

=PSoC Microcontrollers=
Most microntroller platforms (eg. [https://www.arduino.cc/ Arduino], [https://www.microchip.com/design-centers/microcontrollers/ PIC]) have fixed hardware peripherals the developer has access to, as well as a CPU that can execute software commands written in a language such as C. PSoC offers all of this plus reconfigurable hardware and interconnect fabric to allow almost any hardware device to be routed to almost any general purpose input/output (GPIO) pin on the device. Additionally, PSoC also offers analog component blocks such as digital to analog converters (DACs), analog to digital converters (ADCs), and amplifiers.

=Setting up the project=
{{Screenshot|File:psoc_project.png|PSoC Creator project creation}}
To begin working with PSoC, download [https://www.cypress.com/products/psoc-creator-integrated-design-environment-ide PSoC Creator]. This is an IDE that will allow you to create new PSoC projects and program your PSoC mircrocontroller. Create a new project by clicking '''File''' and selecting '''New Project'''. For this project we will assume you are using the PSoC 5 development boards used in the microcontrollers class (CY8CKIT-059), so select this as the target kit (see the image above). At the next dialog, select an '''Empty''' project, and click next. Then give your workspace and project a name (eg. Blink Workspace, Blink Project). A project is simply a design to be implemented on some PSoC hardware device, while a workspace is a container for multiple projects. For this example we will only have a single project within the workspace, but you could possibly have more (eg. a bootloader program and a bootloadable project).

Once your project is created you will be presented with a white box with a dotted grid. This is a blank schematic sheet where hardware peripherals can be added from the component catalog on the right hand of the screen. You will also see you workspace explorer where all workspace files can be found on the left hand of the screen. For this design the only hardware component that will be needed is a digital output pin. Add the pin component from the catalog folder '''Ports and Pins''' to your schematic and double click on the schematic component to configure it as shown in the figure below. Change the name of the pin component to LED_PIN to give it some contextual meaning in the project.

{{Screenshot|Image:psoc_pin.png| Blue shows the schematic component symbol, red shows the catalog entry, and orange shows the pin configuration settings}}

=Blinking an LED with code=
In PSoC you can blink an LED using software or hardware. Let's begin by using software. First, let's assign our pin component in the schematic to an appropriate device pin on the chip. To do this, look at the workspace explorer on the left and select the '''Pins''' entry. Configure your pin to use '''P2[1]''' (ie. device pin 63). This is pin is already connected to an LED on the PSoC 5 development board. Your pin menu should look like the picture below.

{{Screenshot|Image:psoc_pin_menu.png| PSoC pin assignment menu}}
Once the pin is assigned click on the '''Build''' menu and select '''Generate application'''. This will tell PSoC Creator to create code APIs that you can use in your software to make things easier. Next double click the '''main.c''' file in the workspace explorer so that we can begin writing code. Enter the following code into your main.c file.

<pre>
#include "project.h"

int main(void)
{
    CyGlobalIntEnable; /* Enable global interrupts. */

    /* Place your initialization/startup code here (e.g. MyInst_Start()) */

    for(;;)
    {
        LED_PIN_Write(1);
        CyDelay(1000);
        LED_PIN_Write(0);
        CyDelay(1000);
    }
}
</pre>

Let's analyze this code to see what it is actually doing. 

This line includes the generated code APIs that are defined in project.h.
<pre>#include "project.h"</pre>

This code enables [[Electrical Onboarding/PSoC Polling and interrupts#interrupts|interrupts]] on the device. Below this is where any initialization and setup routine code would be placed if any were needed. In this example no setup is required.

<pre>
CyGlobalIntEnable; /* Enable global interrupts. */

/* Place your initialization/startup code here (e.g. MyInst_Start()) */
</pre>

This code drives the pin to a logic 1 (3.3V on PSoC5 devices) using the generated API macro '''LED_PIN_Write(1)'''. It then delays program execution for 1000 milliseconds with the API macro '''CyDelay()'''. It repeats this process to drive the pin to a logic 0 (0V/GND). This will give the effect of having the PSoC board's LED blink at a rate of 0.5 Hz (on for 1 second, off for 1 second). The '''for(;;)''' loop condition makes it so this code will be repeated indefinitely as long as the device has power.

<pre>
for(;;)
{
    LED_PIN_Write(1);
    CyDelay(1000);
    LED_PIN_Write(0);
    CyDelay(1000);
}
</pre>

An important thing to note is that the generated code APIs use the names you provide to the components in the schematic. If you changed your '''LED_PIN''' to be named '''LIGHT''', for example, the code would change to the following:

<pre>
for(;;)
{
    LIGHT_Write(1);
    CyDelay(1000);
    LIGHT_Write(0);
    CyDelay(1000);
}
</pre>

Once you understand this code well enough, go ahead and program the PSoC. Plug the board's USB connector end into a USB port on your PC. Then select '''Debug''' and '''Program'''. The dialog box should autodetect your PSoC device, so just click program and your code should upload to the PSoC and the LED should begin blinking immediately.

=Exercise 1=
Try adding four LEDs to a breadboard circuit with 1K ohm resistors in series. Connect the anode of each LED to a PSoC pin as shown in the schematic below. Write some code to create a binary counter that will count up every one second, and reset to 0 once a value of 0x10 (16 in decimal) is reached. In the PSoC Creator schematic, call each of your pins '''LED0, LED1, LED2,''' and '''LED3''' in order to match the solution code.

{{Screenshot|Image:led_counter.png| Binary LED counter schematic using PSoC5}}

<div class="toccolours mw-collapsible mw-collapsed" style="width:1000px; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Solution</div>
<div class="mw-collapsible-content">
<pre>
#include "project.h"

int main(void)
{
    int count = 0;
    char pin_val[4];

    CyGlobalIntEnable; /* Enable global interrupts. */

    /* Place your initialization/startup code here (e.g. MyInst_Start()) */

    for(;;)
    {
        pinval[0] = count&1;
        pinval[1] = (count&2)>>1;
        pinval[2] = (count&4)>>2;
        pinval[3] = (count&8)>>3;

        LED0_Write(pinval[0]);
        LED1_Write(pinval[1]);
        LED2_Write(pinval[2]);
        LED3_Write(pinval[3]);

        count++;
        count = count%0x10;

        CyDelay(1000);
    }
}
<pre>
This code works by incrementing a counter variable every second. The counter variable is used to determine the pin state of each LED. For LED0, since it is representing the least significant bit (LSB) of the binary number it will be bit-wise ANDed with the LSB of count (i.e. '''pinval[0] = count&1'''). This will give a value of 1 when the LSB is a 1, and 0 when the LSB is a 0. 

We repeat this logic for the other pins as well, but need to do a bitwise shift. If we just did '''pinval[1] = count&2''' then when the second bit of the count variable is a 1, '''pinval[1] = 2''' which is not a valid argument for the '''Write()''' macro that only accepts a value of 1 or 0. The extra bitwise shift effectively divides by 2 for every shift done, so 2/2 = 1 which is valid. This logic is used for the other two pins as well.
</div></div>