ECE 2534 - Lecture 04 - Documentation and Connections 10:10 Purpose Last lecture, we introduced Code Composer Studio and some background ideas in C compilation. This lecture, we will discuss the connectivity of the kit. Namely: - how the components on the PCB connect to the microcontroller chip pins - how the microcontroller chip pins connect to microcontroller peripherals - how the microcontroller peripherals connect to to microprocessor inside of the microcontroller - how the software on the microcontroller can read from/ write to the microcontroller peripherals - how the driver library can help ease writing software that works with microcontroller peripherals There are many different abstraction levels, with some of them at the level of the PCB, some of them at the level of the hardware chips, and some of them at the level of the software. We do not have to know all of the details of every abstraction level on day 1. However, we have to understand how these different abstraction levels 'fit', how they connect to one another. That is the key objective of this lecture. A related question to this topic is: where can you find the required documentation? How do you navigate it? We will discuss these abstraction levels by means of the example of a single peripheral: the GPIO. Other peripherals use similar documentation practices, so you'll notice that finding documentation (software and hardware) for other peripherals is similar to the way it's done for GPIO. Here is the documentation stack. We will refer to it as we work through this lecture Document Level MSP432P402R Launchpad Guide PCB This document describes the main micrcontroller board and shows how devices (eg LEDs, switches) connect to the microcontroller BOOSTXL Plug In Module PCB This document describes the plug-in board with joystick, lcd display, additional chips, connect to the microcontroller board. MSP432P401R Datasheet Microcontroller This document describes the structural details of the microcontroller chip. Consult it for block diagram, memory map, overview of peripherals. MSP432P401R User Guide Microcontroller This document describes the detailed operation of peripherals. You would consult the data sheet to understand what the peripheral does, and you would consult the user guide to understand how to program it. Driverlib User Guide Software This document describes the software library functions that can be used to program peripherals. 10:12 Chip Package We had a glimpse of GPIO in the Impatient LED example. - In software: GPIO_setAsOutputPin(GPIO_PORT_P1, GPIO_PIN0); and GPIO_toggleOutputOnPin(GPIO_PORT_P1, GPIO_PIN0); - Software to hardware: C -> chip pin -> LED 1 logic high current flows, LED on 0 logic low no current flows, LED off Now, let's look at the GPIO pin in more detail. First, let's find out how many GPIO's there actually are. From the software API, it appeared as if there are many ports (up to 12) that each have 16 bits. The data sheet will show how many GPIO's there actually are. The microcontroller on the launchpad is a MSP432P401RIPZ. Page 8 of the data sheet shows the pinout. The package has 100 pins, which are counted counterclockwise (when you look at the chip from the top). Let's look at some of the labels that are with each pin. Pin 1: P10.1/UCB3CLK Pin 2: P10.2/UCB3SIMO/UCB3SDA Pin 3: P10.3/UCB3SOMI/UCB3SCL Pin 4: P1.0/UCA0STE Pin 5: P1.1/UCA0CLK etc .. What does this mean? Physical pins on a microcontroller chip can serve multiple purposes. For example: P10.1/UCB3CLK means that this pin can work either as P10.1 (bit 1 from port P10) or else as UCB3CLK (the clock of serial bus UCB3) Which of these two functions it will implement at any given moment, depends on the configuration of the microcontroller. Typically, you have to choose: a pin can serve only one purpose at a given time. It may be possible, of course, to reconfigure the microcontroller during software, and hence repurpose a pin. In the examples that we will be discussing, we will opt for a single function per pin, per program. So in this case, Pin 1 would be either P10.1, or else UCB3CLK. 10:18 GPIO Ports If we would enumerate all pins on the package, we would be able to identify all GPIO pins available. We can find a quicker answer by consulting the datasheet, page 17, section 4.3. There, you will find the following ports available (check the 'PZ' column for the right 100-pin pacakage). Port #bits P1 8 P2 8 P3 8 P4 8 P5 8 P6 8 P7 8 P8 8 P9 8 P10 6 PJ 6 So 84 pins can be used as input/output ports. We can actually find a schematic of a GPIO pin in the data sheet of the MSP432: see section 6.12 (input/output diagrams) Let's study port P1 in detail - that is on page 138. That schematic describes port P1, bit 0 to bit 7. So you have to imagine this schematic is replicated 8 times on the chip. We can use it to drive a digital logic high on a pin OR We can use it to read the digital logic level from a pin The schematic contains several labels such as PyREN.x PyDIR.x PyOUT.x PySEL1.x PySEL0.x PyIN.x Py.x -> chip pin The y and x can be replaced by a port number and port bit respectively. So, for the 8 bits of port P1, there would be the following bits P1REN.0 to P1REN.7 P1DIR.0 to P1DIR.7 P1OUT.0 to P1OUT.7 P1SEL1.0 to P1SEL1.7 P1SEL0.0 to P1SEL0.7 P1IN.0 to P1IN.7 P1.0 to P1.7 -> chip pin In other words, each bit of the 8 bits of port P1 can be individually controlled. Each chip pin has 6 'control' bits REN DIR OUT SEL1 SEL0 IN These control bits are visible from software, i.e. a C program can read them or set/reset them. Let's first consider the basic port functionality: input or output pin. - As an output pin, the chip pin must be driven. When is the chip pin driven? SEL0 = 0 SEL1 = 0 DIR = 1 Once the chip pin is driven, its value is defined by OUT - As an input pin, the chip pin must not be driven SEL0 = 0 SEL1 = 0 DIR = 0 Once the buffer is removed from the chip pin, the chip pin value can be read from IN This is the default functionality, and there are many variations on it possible (see page 139 ff in datasheet) This is where the userguide for MSP432P4 comes in handy. Chapter 12 of the user guide explains in detail the various configurations available on a GPIO pin. Furthermore, the user guide often explains aspects or subtleties that are difficult to capture in a schematic or in a table. We give two additional examples: (1) pull-up/pull-down resistors in IO ports and (2) multi-functional pins For example, when the chip pin is used as an input, we can connect an internal pull-up or pull-down resistor. To connect the resistor, we have to put REN to 1 while the port is configured as input (not driven). Next, we need to select pull-up or pull-down by writing a logic-1 or logic-0 to OUT. We will see an example of pull-up resistor input when we read switches from the board. A second example is that it is possible to use the chip pin for functionality different from P1. Recall that chip pins are multi-functional. E.g pin P1.0/UCA0STE can work either as bit 0 of port P1 or else as UCA0STE. To get the UCA0STE functionality, we have to configure SEL0 = 0 and SEL1 = 0. In that case, the connections 'From module' on the diagram (in the datasheet) will apply, where 'From module' simply means: the funtionality of the pin is defined by a module (i.e. peripheral), rather than software. As you scroll forward through the datasheet (from port P2, P3, P4, ..) you will find that not all port pins are identical. Some of them have extra functionality or extra hardware, eg. because they also need to carry analog signals. 10.30 Connnecting hardware to the chip pins. - We discussed the example of a port bit P1, which can work as an input or an output. The general notation for port pins is Py.x for bit x from port y. So bit 3 of port P1 would be P1.3 - We can find this notation not only in the datasheet of MSP432P4, but also in the board documentation. - There are two documents that describe the board documentation: - Launchpad Guide - BoostXL Guide - Check the PCB: There are two switches on the side: S1 and S2 S1 is marked P1.1 S2 is marked P1.4 So this means S1 is connected to bit 1 of port P1 while S2 is connected to bit 4 of port P1 - Schematics: Let's check the schematics for these two buttons. Figure 29 of the Launchpad Guide (Schematics 2 of 6) You see the two user buttons in the middle-top. When you press a button, it grounds the signal. When you release a button, the signal remains floating. The signals are connected to microcontroller pins, check Schematics 1 of 6. So, reading the buttonfs will be an application for an input port pin with pull-up resistor! When the button is not pressed, we will read a logic-high from P1.1 (or P1.4). When the button is pressed, we will read a logic-low from P1.1 (or P1.4) We can also find connectivity for the LEDs: P1.0 drives a (red) LED -> that is what impatient LED uses P2.0, P2.1 and P2.2 dives a red, green, blue LED respectively. These three LED are housed in a single package. So, we can generate multiple colors by turning LEDs on and off. (By controlling the 'intensity' of the LED we can even generate arbitrary color combinations ..!) - In the case of the boostXL, the connectivity goes as follows: The BoostXL PCB contains several different chips, sensors, etc. For example, it contains two buttons S1 and S2. If we check the PCB, we see they're marked 'J4.33' and 'J4.32'. The 'J' notation is generally used to describe CONNECTORS. In this case, there are four rows of pins connecting the launchpad to boostxl. These four rows are labeled J1, J2, J3, J4. J4.33 means: pin 33 of connector J4. Now, if we want to find out how these switches are connected to the microcontroller, we would work as follows: a/ Find how the switch connects to the connector (on BoostXL) b/ Find how the corresponding connector pin connect to MSP (on Launchpad) Note that there is a nice figure in the Launchpad manual (Figure 11) that shows how these pins are connected. We will discuss BoostXL connectivity in further detail in the figure. For now, we will focus on the switches and LEDs on the main microcontroller board. 10.40 Connnecting the software to GPIO In order to read/write GPIO pins, we need to configure the software. This is where the labels PyREN.x PyDIR.x PyOUT.x PySEL1.x PySEL0.x PyIN.x come in handy. These labels are implemented in the microcontroller as software-visible registers. 'Software Visible Registers' means that you have a pseudo-variable such as P1OUT P1IN P1DIR P1REN that you can read and write from. These are not 'real variables' such as int i; These registers P1OUT, P1IN, ... are defined when you include driverlib.h. Let's look at an example: #include int main(void) { volatile uint32_t i; // Stop watchdog timer WDT_A_hold(WDT_A_BASE); P1DIR = 1; // P1.0 as output P1REN = 2; // P1.1 as input with pullup/pulldown resistor P1OUT = 2; // select pull-up while (1) { if (P1IN & 2) P1OUT = P1OUT & ~1; else P1OUT = P1OUT | 1; } } This example is a switch-controller LED. It configures bit 0 of port P1 as output (and the other bits as input). It then defines a pull-up configuration for bit 1 from P1REN and it selects a pull-up resistor. It's worthwhile to ponder for a moment what P1IN & 2 or P1OUT & ~1 really means. These are bit-manipulation expressions. The first one, P1IN & 2, tests if the button is pressed. It reads port P1.1, which is bit 1 from port P1. In binary, 2 = 00000010, so it tests exactly bit P1.1 Similarly, P1OUT & ~1, resets a bit from P1OUT. The bit pattern ~1 is ~(00000001) = (11111110) Now, if q is a bit, then q & 1 = 1, but q & 0 = 0. Therefore, P1OUT & ~1 resets exactly bit P1OUT.0 We will discuss bit manipulation expressions early next week, and there will be a homework assignment to cover them. 10:50 The driver library On top of the software application is a driver library, driverlib. It comes with its own manual, driverlib. Section 10 of this manual describes all functions available for GPIO. When you use driverlib functions, you can avoid using the peripheral registers such as P1OUT and P1IN. In fact, any program written using peripheral registers can also be written using driverlib functions. Here is the same program as the previous one: #include int main(void) { volatile uint32_t i; // Stop watchdog timer WDT_A_hold(WDT_A_BASE); GPIO_setAsOutputPin(GPIO_PORT_P1, GPIO_PIN0); GPIO_setAsInputPinWithPullUpResistor (GPIO_PORT_P1, GPIO_PIN1); while (1) { if (GPIO_getInputPinValue(GPIO_PORT_P1, GPIO_PIN1) == GPIO_INPUT_PIN_HIGH) GPIO_setOutputLowOnPin(GPIO_PORT_P1, GPIO_PIN0); else GPIO_setOutputHighOnPin(GPIO_PORT_P1, GPIO_PIN0); } } As you see, it becomes a bit more verbose. Under the hood, these functions do exactly the same as the first program - they result in read/write operations on peripheral registers. The advantage of driverlib is that code is written at a slightly higher level of abstraction. A program with driverlib is easier to port from one microcontroller type to another, since the driverlib is the same for all MSP432 microcontrollers (there are many different types). If you use peripheral registers, you have to ensure that the peripherals remain exactly compatible while moving from one type of MSP432 to another type. Which is preferable, driverlib or register based? Besides the portability argument above, it really depends on the programmer. As you can see, the register based program is more compact, while the driverlib based program is more readable and easier to understand. Both of them have the same functionality. In general, there is no performance difference between a well-written driverlib program and another program that directly programs the peripherals. In this course, I recommend to use driverlib, in first instance, and use only register-based programming if you know exactly how the underlying peripheral works. Hierarchy Documentation ================ =================== User Application Lab Assignment (C Program) HW Assignment | | | | DriverLib | DriverLib Manual | | | | MSP432P401R Micro MSP432 Datasheet | MSP432 User Guide | Launchpad Launchpad User Guide | | BoostXL Sensor Board BoostXL User Guide 10:55 Summary