Atmel Training Material on ASF and Arduino

Slide 1

Slide 1 text

TRAINING MANUAL Customer application support in Atmel Studio Framework AN-9684 Prerequisites  Hardware Prerequisites  SAMD21 Xplained Pro board  IO1 Xplained Pro extension board  OLED1 Xplained Pro extension board  Arduino Zero board  13 x male-to-male connector cable  USB micro cable  Software Prerequisites  Atmel Studio v. 6.2 or later  Atmel Studio Framework (ASF) v. 3.19 or later  Estimated Completion Time:  3-5 hours Introduction Atmel Studio Framework (ASF) has been written with the intention to support a wide range of Atmel’s microcontrollers and hardware boards by providing the customers with easy-to-use drivers and routines. However, in the process of writing firmware for a new hardware, one is very likely to encounter a situation, in which certain modifications are needed in order to support the features of the customer’s end product. Typically, these “customizations” could mean, for example: 1. Changing the user board layout, or porting the application code to a new microcontroller (MCU) 2. Adding support for a new hardware component. 3. Creating or altering a low-level driver in order to reach an accurate performance of a specific peripheral. 4. Creating or changing certain high-level software routines to provide more “tailored” options. Since the cases 3 and 4 require very user-specific needs, in this document, we are going to present a process of achieving the results in the first two situations. The processes will be shown based on SAM D21 family microcontrollers, although the approach presented in this training material is extendable to other MCUs. 9/15/2014

Slide 3

Slide 3 text

Table of Contents Prerequisites......................................................................................1 Introduction.........................................................................................1 Icon Key Identifiers.............................................................................6 Training Module Architecture.............................................................7 1.1 Atmel Studio Extension (.vsix)............................................................7 1.2 Atmel Training Executable (.exe)........................................................7 Part 1. Basic ASF concept explained............................................8 1.1 Short introduction to ASF....................................................................8 1.1.2 Structure............................................................................................8 1.1.3 Folder structure.................................................................................9 Assignment 1 Building a small application.......................................11 1.2 General application concept..............................................................11 1.3 Connect the hardware.......................................................................12 1.4 Create a starting template for developing your application...............12 1.5 Redefine our input/output ports.........................................................15 1.6 Adding the drivers (RTC)...................................................................17 1.7 Configure the module (RTC).............................................................19 1.8 Configure the clock for the module (RTC).........................................20 1.9 Read the sensor input (ADC)............................................................21 1.10 Display the text (OLED)....................................................................24 1.11 Finalizing the application...................................................................25 1.12 Summary on Assignment 1...............................................................27 Part 2. Changing the board.........................................................28 2.1 Background information....................................................................28 Assignment 2 Creating a new board platform...............................32 2.2 Choosing the user board template....................................................33 2.3 Re-definition of new pinout................................................................33 2.4 Restoring the application environment..............................................35 2.5 Porting the application code..............................................................35 2.6 Cosmetic surgery..............................................................................38 2.7 Summary on Assignment 2...............................................................40 2.8 Preparing the project for Assignment 3.............................................40 Part 3 Adding support for a new component..............................42 3.1 Preliminary considerations................................................................43 Customer application support in ASF – Training Manual: 9/15/2014 Page 3 of 90

Slide 4

Slide 4 text

3.2 Understanding and creating the file structure....................................43 3.3 Connecting the files...........................................................................47 3.4 Bringing datasheet into the code.......................................................49 3.5 Creating low-level set of functions.....................................................52 3.5.1 Writing to the display controller........................................................52 3.5.2 Reading from the display controller.................................................54 3.5.3 Resetting of the display...................................................................54 3.5.4 Enabling and disabling the display..................................................55 3.5.5 Turning the display on and off.........................................................55 3.5.6 Setting contrast................................................................................56 3.5.7 Inverting the content........................................................................56 3.5.8 Addressing functions.......................................................................57 3.6 Initialization procedure......................................................................59 3.6.1 Internal initialization.........................................................................59 3.6.2 External initialization........................................................................60 3.7 High-level functions...........................................................................62 3.7.1 Access points: null-display, framebuffer and file structure…............63 3.7.2 Switching the points.........................................................................64 3.7.3 Tying two ends together..................................................................70 3.8 Summary on Assignment 3...............................................................72 Summary on ASF customization processes....................................73 Changing the board......................................................................................74 Adding support for a custom component......................................................75 Appendix A. Complete solution to Assignment 1.............................76 A.1 The body of the main.c file:....................................................................76 A.2 Changes to the conf_clocks.h file..........................................................79 Appendix B. Complete customized component files.......................79 B.1 The body of the oled_controller.h file:....................................................79 B.2 The body of the oled_controller.c file:....................................................81 B.3 The body of the conf_oled_controller.c file:............................................83 Appendix C. Complete customized service files..............................83 C.1 The body of the gfx_mono_null.h file.....................................................83 C.2 The body of the gfx_mono_null.c file.....................................................85 Appendix D. Taking advantage of ASF conventions and APIs........89 D.1 Peripheral module configuration............................................................89 D.2 The meaning of module instance and config struct’s.............................89 Customer application support in ASF – Training Manual: 9/15/2014 Page 4 of 90

Slide 7

Slide 7 text

Training Module Architecture This training material can be retrieved through different Atmel deliveries:  As an Atmel Studio Extension (.vsix file) usually found on the Atmel Gallery web site (http://gallery.atmel.com/) or using the Atmel Studio Extension manager  As an Atmel Training Executable (.exe file) usually provided during Atmel Training sessions Depending on the delivery type, the different resources needed by this training material (hands-on documentation, datasheets, application notes, software & tools) will be found in different locations. 1.1 Atmel Studio Extension (.vsix) Once the extension is installed, you can open and create the different projects using “New Example Project from ASF..." in Atmel Studio. The projects installed from an extension are usually under “Atmel Training > Atmel Corp. Extension Name”. There are different projects which can be available depending on the extension:  Hands-on Documentation: contains the documentation as required resources  Hands-on Assignment: contains the initial project that may be required to start  Hands-on Solution: contains the final application which is a solution for this hands-on Each time a reference is made to some resources in the following pages, the user must refer to the Hands-on Documentation project folder. 1.2 Atmel Training Executable (.exe) Depending where the executable has been installed, you will find the following architecture which is composed by two main folders:  AN-XXXX_Hands-on: contains the initial project that may be required to start and a solution  Resources: contains required resources (datasheets, software & tools…) Unless a specific location is specified, each time a reference is made to some resources in the following pages, the user must refer to this Resources folder. Customer application support in ASF – Training Manual: 9/15/2014 Page 7 of 90

Slide 8

Slide 8 text

Part 1. Basic ASF concept explained 1.3 Short introduction to ASF Atmel Studio Framework (ASF) provides a software interface library interface between Atmel MCU hardware registers and a user’s application code. With a strong focus on usability and portability, it has been organized in four layers, which provide support on different level of abstraction. Starting from the lowest-level, these are: boards, drivers, components and services. In addition to them, ASF provides useful application examples to help customers write their own applications. Figure 1.3.1.1.1. Atmel Software Framework structural layers. 1.1.1 Structure According to the specification ASF, each of these layers is dedicated to supporting our application at a specific level. Knowing of these layers is a key to customize our application project. Let us quickly summarize their purpose: Boards: This layer contains the basic definitions of pinout, as well as initialization of the board (e.g. bringing all I/O ports to a preset configuration). One may think of this layer as a reflection of the board schematic in the software. We will mostly deal with that layer in Assignment 2. Drivers: This layer consists of low-level software routines that are used to handle MCU peripherals, such as the Serial Parallel Interface (SPI), Analog-to-Digital Converter (ADC), Universal Serial Bus (USB), etc. Drivers constitute a fundamental “bridge” between the register- level description and software routines. These APIs provide a more user-friendly interface to the peripheral configuration, comparing to the register-level code. Components: This layer is, in a way, very similar to drivers. However, its intention is to provide a set of routines targeted to handle components that are external to the MCU, such as displays, memories, sensors, transceivers, etc. Since such components usually require some configuration (e.g. configuring their own registers), they often use drivers and for this reason they are placed directly above them. Customer application support in ASF – Training Manual: 9/15/2014 Page 8 of 90

Slide 9

Slide 9 text

Services: This is a high-level layer, which contains pre-made software functions designed to facilitate application-level code. Typical examples could be:  GFX Monochrome library that contains parameterized graphical figures to be displayed,  USB Host to optimize the USB functionality for some devices,  FAT file system to facilitate handling of the file formats, etc. They are placed above all mentioned layers, as they are the least hardware-specific entities. In addition to the four layers that will be the main scope of this training, ASF structure also distinguishes the following: Utilities: They are represented as the gray vertical layer. This layer contains all the compiler abstraction files, which allow using different compilers (currently GCC and IAR). Utilities unify differences in e.g. interrupt handling routines, which might exist between these compilers, as well as definitions of specific types that are characteristic to embedded programming (e.g. uint8_t denoting an 8-bit unsigned integer). Utilities are outside the scope of this training. Applications: This is a bank of few thousands of example applications projects intended to help customers develop their own application. Your code: This layer represents customer application code. 1.3.2 Folder structure ASF predicts a specific folder structure, which reflects the four layers we have just discussed. First of all, all project input files are located under ../src/, wherein we can find the main.c file, asf.h header file and two folders: ASF and config.  The main.c file is the main application code.  ASF.h file is a primary “binder” of our project. It contains #include statements that collect all relevant libraries that are used in our project.  The config folder is where we will find static header files that are related to specific drivers and used for configuring them. (We will use it very often later).  Finally ASF folder that contains all the discussed four layers. The code related to the four-layer (inside ASF folder) is organized through the following subfolders:  common – contains the portion of ASF that is absolutely common to all Atmel MCUs and boards.  sam0 – contains the portion of ASF that is specific to the SAM-cortex M0 devices, such as SAMD21. In case, we select a project based on XMEGA Customer application support in ASF – Training Manual: 9/15/2014 Page 9 of 90

Slide 16

Slide 16 text

The port_init() was, in fact, created following a standard procedure of configuring a peripheral that applies to all devices of the SAM0 family. This is a five step process: 1. Define a configuration structure. We create a struct of a specific type dictated by a peripheral, which will store the configuration settings for a given peripheral module. 2. Load with defaults. We use xxx_get_config_defaults function to set all the predefined values. This makes the configuration easier, as we will only need to focus on specific parts that are relevant for us. 3. Modify the configuration. Depending on the application requirements, we change only the specific values 4. Initialize. We load the modified data to the structure using. 5. Enable. Finally, we set the flag to enable the peripheral. (Sometimes steps 4 and 5 can be combined.) Next, we need to define what LED1, LED3 and BUTTON are. Consequently, let us add the definitions (place them at the beginning of the main.c file). #define LED1 EXT3_PIN_7 #define LED3 EXT3_PIN_6 #define BUTTON EXT3_PIN_9 You might have noticed that once we have added these definitions, the color of the names change from black to purple everywhere inside the project. This is a sign that Atmel Studio “recognizes” these names. This small feature will prove useful in the later parts of this training. In order to enforce the port configuration, we must call the port_init function in the actual code. We do that before the “while” loop – the so-called program loop. port_init(); Finally, let us modify the content of the program loop, such that it constantly checks for the state of the button and adjusts the LED1 state accordingly: while (1) { // Is button pressed? if (port_pin_get_input_level(BUTTON)) { // Yes, so turn LED on. port_pin_set_output_level(LED1, true); } else { // No, so turn LED off. port_pin_set_output_level(LED1, false); } } Now, we should be able to use LED(s) and BUTTON(s) anytime to verify our application. (You may run the code to check if it works correctly. 1.8 Adding the drivers (RTC) Having created a template for our application, the next step is to select the drivers (services and components) that are needed for our application. Let us reflect on our concept of application. In this application we will need to select: Customer application support in ASF – Training Manual: 9/15/2014 Page 16 of 90

Slide 18

Slide 18 text

The window that appears is ASF Wizard. We will use this window anytime we need to add or remove the drivers. Observe that some drivers are already included in our project by default. An example is the PORT driver that contains all functions, macros and definitions used to configure ports and pins in various ways. Remember, we have used some of these functions in the last step. Naturally, the reason the project compiled (and the functions were displayed as red) was that we had this driver already included. Select the RTC driver in the count_callback mode and Add it to the selected modules and Apply the changes. We opt for the callback option as it will provide us with an application interface, which will allow us to act when the counter overflows (we will see that later). In general, ASF Wizard offers us two possibilities of APIs: callbacks and polled. Callback versions make module operating interrupt-driven offering a user to define a function that will be executed upon a certain event (e.g. timer overflow, receiving data through USART, etc.). Polled versions are the opposite – no interrupt will be executed and it is user’s responsibility to check a particular flag. Therefore, polled versions are predominantly used if we want to simplify the code and do not need to define any interrupt-related action. Now let us give a little bit of attention to the pop-up window that just appeared. Figure 1.8.1.1.2. Summary of operations when selecting/deselecting ASF modules. By selecting and adding the RTC driver, we ask the Atmel Studio to include the all files that are relevant to manage the RTC module. Recalling ASF folder structure, observe that a new folder has been added to the following path: ../src/ASF/sam0/drivers path. It is placed inside sam0 folder, suggesting that the files added are exclusive for SAM0 device family. In addition, a compiler symbol ‘RTC_COUNT_ASYNC=true’ has been defined. When looking into the driver files, we can see that they are often written to support more than one configuration, using conditional statements such as #ifdef. In case of the RTC, we have four: count-polled, count- Customer application support in ASF – Training Manual: 9/15/2014 Page 18 of 90

Slide 20

Slide 20 text

void configure_rtc_callbacks(void) { rtc_count_set_period(&rtc_instance, 128); rtc_count_set_count(&rtc_instance, 0); rtc_count_register_callback( &rtc_instance, rtc_overflow_callback, RTC_COUNT_CALLBACK_OVERFLOW); rtc_count_enable_callback(&rtc_instance, RTC_COUNT_CALLBACK_OVERFLOW); } This code configures the Real Time Clock to operate in 16 bit mode with no pre-scaling of the input clock. In addition to that, it initializes and enables the callback function that will be associated with the counter overflow. By setting the period to 128 and count to 0, we will get the rtc_overflow_callback() function execute 4 times a second, if we provide the a 32 kHz clock source to the module. Check the API Documentation and the Quick Start Guide for more options. In the body of the main function (and before the while loop), execute the two initializations: /* Configure and enable RTC */ configure_rtc_count(); /* Configure and enable callback */ configure_rtc_callbacks(); The RTC is now almost ready to work. We have defined all software functions, configured the module and enabled it. The only thing that we still miss is providing it with the correct input clock signal. 1.10 Configure the clock for the module (RTC) In most cases, one will not need to change the clock settings during MCU’s operation. Therefore, ASF provides a convenient way of pre-configuring the clock setting using a separate file. Configure the input clock for the RTC module. Inspect the ../src/config folder and open the conf_clocks.h file. If you need to return to the Solution Explorer, but you have accidentally closed the window, you can open it again in View > Solution Explorer. In the conf_clocks.h file, you will find many options that are available for the clock configurations. The selection process is based simply on changing the #define flags. To keep the promise of executing the rtc_callback_overflow() every quarter of a second, we need to enable the internal 32 kHz clock. In addition, we need to assign it to the General Clock (GCLK) #2, which is intended to function as the RTC. In general, we are not hardware-limited to used GCLK2 for the RTC module. However, GCLK2 is unique in a way, that it is the only clock generator that has only 5 division factor bits. Being in this way reduced, using of GCLK2 is a step to minimize the power consumption. Customer application support in ASF – Training Manual: 9/15/2014 Page 20 of 90

Slide 21

Slide 21 text

Find the relevant blocks of code and replace them with the following settings: /* SYSTEM_CLOCK_SOURCE_OSC32K configuration - Internal 32KHz oscillator */ # define CONF_CLOCK_OSC32K_ENABLE true # define CONF_CLOCK_OSC32K_STARTUP_TIME SYSTEM_OSC32K_STARTUP_130 # define CONF_CLOCK_OSC32K_ENABLE_1KHZ_OUTPUT true # define CONF_CLOCK_OSC32K_ENABLE_32KHZ_OUTPUT true # define CONF_CLOCK_OSC32K_ON_DEMAND true # define CONF_CLOCK_OSC32K_RUN_IN_STANDBY false /* Configure GCLK generator 2 (RTC) */ # define CONF_CLOCK_GCLK_2_ENABLE true # define CONF_CLOCK_GCLK_2_RUN_IN_STANDBY false # define CONF_CLOCK_GCLK_2_CLOCK_SOURCE SYSTEM_CLOCK_SOURCE_OSC32K # define CONF_CLOCK_GCLK_2_PRESCALER 32 # define CONF_CLOCK_GCLK_2_OUTPUT_ENABLE false Some flags just need a true or false input, whereas some offer more options. If you wish to investigate further, mark e.g. SYSTEM_OSC32K_STARTUP_130 and press Alt + G. This will bring you to the original definition. The clock is configured as desired – we assign 32 kHz internal oscillator to GCLK2, which we later pre-scale with a factor of 32, thus obtaining a 1 kHz clock. Using the count_set_period; function with a 1024 value would result in RTC overflowing exactly once a second. Setting it to a quarter of this value makes this occurrence 4 times more frequent. You may want to verify your result. Try inserting port_pin_toggle_output_level(LED3); inside the rtc_callback_overflow() function. In this case, start without debugging (by clicking button). 1.11 Read the sensor input (ADC) For now our application is only blinking an LED. Let us move to the new step, which will involve reading the state of the light sensor. As discussed in the general concept, this part will require us to use the Analog-to- Digital Converter. Although it is a different peripheral module, we are going to follow a very similar procedure. All we need is to:  Add the ADC driver through ASF Wizard  Configure the clock source for the module  Create a configuration function, in which we will:  Create a struct for ADC configuration  Load the default values  Adjust the parameters according to our application’s needs  Assign these changes to the peripheral  (optionally) register a callback  Create a callback – define what it should do  Enable the module  In this case – initialize the first ADC conversion  Finally, do something with the ADC results in the application code Customer application support in ASF – Training Manual: 9/15/2014 Page 21 of 90

Slide 22

Slide 22 text

Using the ASF Wizard, add the ADC driver to our application. In the configuration settings, choose the callback version. The ADC driver is added to the project. If we check the “../src/ASF/sam0/drivers/”, we should see that the ADC folder containing libraries is included. Enable the Generic Clock #3, which we will use for the ADC module. Let the internal 8 MHz oscillator remain the input source for the clock. In conf_clocks.h replace the relevant block of the code with the following: /* Configure GCLK generator 3 */ # define CONF_CLOCK_GCLK_3_ENABLE true # define CONF_CLOCK_GCLK_3_RUN_IN_STANDBY false # define CONF_CLOCK_GCLK_3_CLOCK_SOURCE SYSTEM_CLOCK_SOURCE_OSC8M # define CONF_CLOCK_GCLK_3_PRESCALER 30 # define CONF_CLOCK_GCLK_3_OUTPUT_ENABLE false The GCLK 3 is now enabled and ready to be used. Configure and initialize the ADC with the following parameters:  Gain factor: 2  Clock prescaler: 512  Reference: input VCC1  Positive PIN: PIN #8  Resolution: 12-bit The light intensity is acquired by using of a phototransistor (datasheet), whose collector-emitter current is proportional to the light intensity illuminating of transistor’s base. Since the transistor is connected as pull-down, the voltage measured by the ADC becomes inversely proportional to the light intensity. A simple way of correcting for this is to subtract the measured value from the top value of the ADC output, which is 0xFFF for 12-bit configuration. Given that the voltage we measure can swing from GND to VCC, we will use the internal VCC divided by 2. Note that it is not the only “correct” way to configure of the ADC. However, it suffices for our application. Create the light_sensor_init()function, which we will use for configuring of the ADC. Use the following code:  Declare the following global variables and constants: struct adc_module adc_instance; #define ADC_SAMPLES 1 uint16_t adc_result_buffer[ADC_SAMPLES]; volatile bool adc_read_done = false; Here, we define the global structure for holding the ADC configuration. Next, we define the number of samples that we want to receive upon each ADC conversion. As mentioned before, we are going to focus on customization process rather than the application itself; hence one sample is perfectly enough. According to ASF documentation, the ADC writes its measurement to a buffer. This is why define a table in the third line of this code. Finally, we need a software Customer application support in ASF – Training Manual: 9/15/2014 Page 22 of 90

Slide 23

Slide 23 text

flag to signalize when the ADC conversion is finished. It is signified as volatile since this variable is going to be accessed from different parts of the program.  Create the initialization function (before the main function in the main.c file): void light_sensor_init(void) { struct adc_config config_adc; adc_get_config_defaults(&config_adc); config_adc.gain_factor= ADC_GAIN_FACTOR_DIV2; config_adc.clock_prescaler = ADC_CLOCK_PRESCALER_DIV512; config_adc.reference = ADC_REFERENCE_INTVCC1; config_adc.positive_input = ADC_POSITIVE_INPUT_PIN8; config_adc.resolution = ADC_RESOLUTION_12BIT; adc_init(&adc_instance, ADC, &config_adc); adc_enable(&adc_instance); adc_register_callback(&adc_instance, adc_complete_callback, ADC_CALLBACK_READ_BUFFER); adc_enable_callback(&adc_instance, ADC_CALLBACK_READ_BUFFER); } This implementation is following the general procedure of loading the default configuration, changing the necessary parameters, initializing and enabling the module and registering a callback.  Finally, call the light_sensor_init() in the main function, before the while loop. Configure the callback function. Place the following code, before the main function. void adc_complete_callback(const struct adc_module *const module) { adc_read_buffer_job(&adc_instance, adc_result_buffer, ADC_SAMPLES); adc_read_done = true; } The way our program is going to work with the ADC is to call for this callback function every time it completed a new conversion. In this function, we ask the ADC to perform a new conversion, which will keep the ADC working in the background at all times. Last, but not least, we need to “manually” trigger the first conversion. Otherwise, the ADC will be ready to work, but always waiting for the first call to start “the chain reaction”. Place the following code just before the main loop in the main.c file, but after light_sensor_init(). system_interrupt_enable_global(); adc_read_buffer_job(&adc_instance, adc_result_buffer, ADC_SAMPLES); while (adc_read_done == false) { /* wait for asynchronous adc read to complete */ } Customer application support in ASF – Training Manual: 9/15/2014 Page 23 of 90

Slide 24

Slide 24 text

The ADC part is operational now. Our application reads the sensor data. Configuring of ADC follows a certain procedure that is also applicable to other peripheral modules. Watching more carefully, we could see that in case of ADC example, two structures have been defined:  struct adc_module adc_instance;  struct adc_config config_adc; They both serve different purpose and so they should not be confused. The first one – adc_instance –serves as a hardware module representation in the software. It contains for example sampled data in a buffer or information about the status of it. The second one – config_adc – is used only to configure and initialize the module. In most cases, the first one should be declared as global, while in the second case it can be declared as local or global depending on the application. More information concerning the ASF code optimization is available in Appendix D. 1.12 Display the text (OLED) Finally, we have reached the last part of our program. In this part we are going to add and configure the GFX Monochrome – System Font, which is a service – ASF’s highest layer. The way we implement its features in the project is again going to follow the standard process. However, in order to prepare us for the later exercises, we are going to give it a little bit more attention. Add the OLED functionality and display the messages about the ambient light level. Use the ASF Wizard and add the GFX Monochrome – System Font service to our project. Select the ug_2832hsweg04 for the display driver and polled version of the SERCOM SPI driver. In order to change these options, you must have expanded ASF feature “tree” in the Selected Modules window. Let’s spend a moment and observe the dependencies. Figure 1.12.1.1.1. View of peripheral modules supported by the application. Customer application support in ASF – Training Manual: 9/15/2014 Page 24 of 90

Slide 25

Slide 25 text

The GFX Monochrome – System Font (service) incorporates two blocks: the Monochrome Graphic Library (service) and the Graphical Primitives (pixel, line, square, and circle) (service). The first one relies upon another service, which in our case is called Display Driver (service): ug_2832hsweg04. By selecting this one, instead of the default null driver, ASF Wizard includes the underlying component layer, which is the SSD1306 OLED controller. This is a physical device that is used to drive the OLED screen that we use. The component layer therefore “translates” all the high-level routines to a language that is suitable for this very display. Finally, the choice of the SSD1306 OLED controller involves ensuring that even lower-level MCU module related drivers are also included in the project. You have probably noticed that the PORT and SYSTEM had already been added before. This is true, but they are not being added twice. We will later see how they are exactly implemented without causing a conflict. At this step, however, it is useful to remember, which of the low-level drivers are needed to support our particular component and ASF. Initialize the OLED by placing the following code before the while loop in the main.c file. gfx_mono_init(); The OLED is now enabled and ready. In fact, we did not need to spend much time configuring it, because the largest part is essentially performed automatically through ASF Wizard. 1.13 Finalizing the application So far we have added, configured and enabled all three modules that we need in our project. However, we still need to complete the application code. As mentioned in the introduction, we do not want to spend much time on the application. If you wish to learn how to create a similar application with more optimal allocation of resources and robustness, we recommend to you this training. What our application needs to do is to convert the raw data stored in the adc_result_buffer to a readable format and display this information on the screen. We need to create the remaining part of the code. Declare the global variables and constants in the main.c file. #include char disp_string[10]; #define APP_STR_LENGTH 16 volatile bool oled_refresh_ready = false; uint16_t brightness = 0; #define UPPER_BOUND 4000 #define LOWER_BOUND 200 The first line of the code includes the stdio.h library, which we will need to support creating the string of text. Create a function display_result(), with the following piece of code: void display_result(void) { brightness = 4096 - adc_result_buffer[0]; if (brightness < LOWER_BOUND) { gfx_mono_draw_string("Min", 76, 0, &sysfont); Customer application support in ASF – Training Manual: 9/15/2014 Page 25 of 90

Slide 31

Slide 31 text

 board.h stored in ../src/ASF/common/boards/  user_board.h stored in ../src/ASF/sam0/boards/  init.c stored in ../src/ASF/sam0/boards/  conf_board.h stored in ../src/config/ Each of these files has a specific purpose. board.h This file acts as a selector. It contains the list of all boards and extensions supported by Atmel. Based on the choice we make when deciding to use the right template, this file is used to select the correct pre-settings for each case. Choosing SAMD21 Xplained Pro, for example, results in adding: ../src/ASF/sam0/boards/samd21_xplained_pro/samd21_xplained_pro.h. Importantly, one of the possible choices is a user board. user_board.h This is the definition of all board’s pinout. It translates the MCU’s pins (e.g. PA21) to whatever is connected to them (e.g. ADC[7] or SPI_MISO) thus separates the abstraction layer and makes our application development easier and more robust. init.c This file is used for I/O pin configuration. It is a place for initialization of all pins that is required by components connected to them. conf_board.h We might face a situation, in which our intention is to create a prototyping board (similar to Arduino!), in which some connectors are intentionally left open with a possibility to be connected to different peripherals. In such situation, it would be practical to define special logical flags that can be used to indicate, whether a given peripheral is connected or not. For example: in our application, we have decided to connect OLED to a group of pins. However, although we pretend it is hard-wired to our MCU, we may want to replace it with some other component in the future. In such cases, a set of flags could in principle prevent us from possible errors resulting from using conflicting names. Before we start a new project, have a look at how these four files look when using SAMD21 Xplained Pro board. See how they look. 2.2 Choosing the user board template We need to open a new template that is relevant for our new board. Open a new project in Atmel Studio just like you did before. Add it to the existing solution. Name it as: Application2. Choose SAMD21G18A as a microcontroller and select user board in the menu. This time have a template for SAMD21G18A and a user board. By generating this template, we have actually enforced a new definition in board.h file. Customer application support in ASF – Training Manual: 9/15/2014 Page 31 of 90

Slide 34

Slide 34 text

 GFX Monochrome – System Font (service) with:  Display driver (service): ug_2832hsweg04  SERCOM SPI – Serial Peripheral Interface (driver): polled  Delay routines (service): systick We have restored all necessary drivers needed in our project. Restore the correct clock configuration in conf_clocks.h file. To recall, we have used these settings. We have now the exact same clock configuration. Bring back the application code. Replace the content of the new main.c file with our application code. Finally, we obtain the same working environment of our project with one difference – we have changed the board layer. 2.5 Porting the application code So far we have done three things:  we have defined a new board platform  restored the same driver environment  restored the clock configuration settings  restored the application code (main.c file) In order for the application to work, however, there is one final step, which is to “connect” the old application to the new board. In other words, we must ensure that all modules are configured in a way that recognizes the new pin configuration. Assign the new configuration to the ADC module. Find the light_sensor_init() function, where the ADC is configured. Change the positive input setting. If we hover a mouse over the following flag ADC_INPUTCTRL_MUXPOS_PIN8 and press Alt + G, we will be brought to adc.h file, which contains all possible PINMUX definitions. The PINMUX, or in another words – Pin Multiplexer, is a piece of the MCU hardware that decides what peripheral module function is assigned to a particular pin. In our case, we need change the ADC input from pin PB00 to PA02. Based on the information in the datasheet we need to select AIN[0] instead of AIN[8]. We change the following line of code: config_adc.positive_input = ADC_INPUTCTRL_MUXPOS_PIN0; Customer application support in ASF – Training Manual: 9/15/2014 Page 34 of 90

Slide 35

Slide 35 text

Do not confuse definitions related to PINs with definitions related to PINMUX. Always look at each pin’s function. The ADC sources data from the correct new pin. Assign the new configuration to OLED. Open the “../config/conf_ssd1306.h” file and change the setting to support our new board. As in the ADC example, we need to look at the PINMUX just as well as the pins themselves. Here, the OLED SSD1306 driver uses a hybrid configuration of three SERCOM-SPI pins together with GPIOs. Obviously, none of the definitions based on the SAMD21 Xplained Pro board is now recognized. In order to examine what is the meaning of each of the definitions, we would need to step back and look into our previous code, press Alt + G, and inspect the code or look into ASF documentation as discussed in page 18. Here, we will just discuss the solution. Assign the new SERCOM module. Replace the following line of code. #define SSD1306_SPI EXT3_SPI_MODULE #define SSD1306_SPI SERCOM1 In fact, EXT3_SPI_MODULE flag, refers to SERCOM5, which is defined in “../src/ASF/sam0/boards/samd21_xplained_pro/samd21_xplained_pro.h” – the equivalent file to our user_board.h. Assign the new GPIO pins, by replacing the following code: #define SSD1306_DC_PIN EXT3_PIN_5 #define SSD1306_RES_PIN EXT3_PIN_10 #define SSD1306_CS_PIN EXT3_PIN_15 #define SSD1306_DC_PIN DISP_CMD #define SSD1306_RES_PIN DISP_RES #define SSD1306_CS_PIN DISP_SS Change the SERCOM SPI PINMUX setting, by replacing the following line: #define SSD1306_SPI_PINMUX_SETTING EXT3_SPI_SERCOM_MUX_SETTING #define SSD1306_SPI_PINMUX_SETTING SPI_SIGNAL_MUX_SETTING_E Again, the EXT3_SPI_SERCOM_MUX_SETTING is defined in samd21_xplained_pro.h file and equal to SPI_SIGNAL_MUX_SETTING_E. Here, we leave the same setting for simplicity. However, at this stage, it is useful to know about the other possibilities. The SPI_SIGNAL_MUX_SETTING_X, is in fact configuring the pins’ functionality internally within SERCOM SPI module – the so-called PAD[x]’s. In SAM-D series, the SERCOM itself can be reconfigured to support various serial communication protocols (hence its name). Furthermore, even within SERCOM SPI, there exist possibilities to define each of the PADs to a given function, such as MOSI, MISO, SCK or ~SS, depending on the master or slave mode of operation. This assignment is performed by using DIPO and DOPO bit fields (Data-In/Out PinOut) in CTRLA register. If you hover a mouse over SPI_SIGNAL_MUX_SETTING_E and press Alt + G, you will be able to see the exact settings. Confronting the datasheet, having written 0x0 to DIPO and 0x1 to DOPO, gives the PADs the following functions (assuming the MCU operates in master mode regarding the OLED): Customer application support in ASF – Training Manual: 9/15/2014 Page 35 of 90

Slide 36

Slide 36 text

 PAD[0] is MISO (Master-In Slave-Out)  PAD[1] is ~SS (inverted Slave Select)  PAD[2] is MOSI (Master-Out Slave-In)  PAD[3] is SCK (Serial Clock) The last step is to assign the correct settings in the PINMUX, associating the SERCOM module’s PADs with physical pins. Remember that we use SERCOM1. Consequently, the pins associated with this functionality are PA16-19. We replace the code: #define SSD1306_SPI_PINMUX_PAD0 EXT3_SPI_SERCOM_PINMUX_PAD0 #define SSD1306_SPI_PINMUX_PAD1 PINMUX_UNUSED #define SSD1306_SPI_PINMUX_PAD2 EXT3_SPI_SERCOM_PINMUX_PAD2 #define SSD1306_SPI_PINMUX_PAD3 EXT3_SPI_SERCOM_PINMUX_PAD3 #define SSD1306_SPI_PINMUX_PAD0 PINMUX_PA16C_SERCOM1_PAD0 #define SSD1306_SPI_PINMUX_PAD1 PINMUX_UNUSED #define SSD1306_SPI_PINMUX_PAD2 PINMUX_PA18C_SERCOM1_PAD2 #define SSD1306_SPI_PINMUX_PAD3 PINMUX_PA19C_SERCOM1_PAD3 You have probably noticed that PAD[1] is assigned to “no function”. This is because the SSD1306 OLED driver uses a GPIO pin instead, which has been defined earlier in the code. This is purely component-specific setting and at this stage, we do not need to be concerned about that as long as the changes we provide are consistent. We have specified all necessary setting changes for ASF drivers. 2.6 Cosmetic surgery Before we ultimately run our old application code on the new platform, let us perform few delicate corrections and enhancement to our code, which will improve its robustness and facilitate maintenance. Include the PINMUX definitions to the user_board.h. Open user_board.h and place the following code inside the #ifdef OLED_PRESENT … #endif statement. #define DISP_SPI SERCOM1 #define DISP_SPI_PINMUX_SETTINGS SPI_SIGNAL_MUX_SETTING_E #define DISP_SPI_PAD0 PINMUX_PA16C_SERCOM1_PAD0 #define DISP_SPI_PAD1 PINMUX_UNUSED #define DISP_SPI_PAD2 PINMUX_PA18C_SERCOM1_PAD2 #define DISP_SPI_PAD3 PINMUX_PA19C_SERCOM1_PAD3 Open conf_ssd1306.h and use the following code to replace the definitions: #define SSD1306_SPI DISP_SPI #define CONFIG_SSD1306_FRAMEBUFFER #define SSD1306_DC_PIN DISP_CMD #define SSD1306_RES_PIN DISP_RES #define SSD1306_CS_PIN DISP_SS Customer application support in ASF – Training Manual: 9/15/2014 Page 36 of 90

Slide 37

Slide 37 text

#define SSD1306_SPI_PINMUX_SETTING DISP_SPI_PINMUX_SETTINGS #define SSD1306_SPI_PINMUX_PAD0 DISP_SPI_PAD0 #define SSD1306_SPI_PINMUX_PAD1 DISP_SPI_PAD1 #define SSD1306_SPI_PINMUX_PAD2 DISP_SPI_PAD2 #define SSD1306_SPI_PINMUX_PAD3 DISP_SPI_PAD3 Add the following line to the #ifdef LIGHT_SENSOR_PRESENT … #endif statement. #define LIGHTSENSOR_POSITIVE_INPUT ADC_POSITIVE_INPUT_PIN0 Change the corresponding line in the main.c file: config_adc.positive_input = ADC_POSITIVE_INPUT_PIN0; config_adc.positive_input = LIGHTSENSOR_POSITIVE_INPUT; The SSD1306 OLED driver and the ADC driver are now separated with one layer of abstraction from the connection on our board. In other words, if we decide to reconfigure the connections again or port this application to yet another board, we will only need to apply the changes in the conf_board.h file. Remove all legacy definitions from the main.c file. When we first created the application, we have in fact mixed the application code slightly with the board-related definitions. We did that, because we wanted to quickly create a working code and we were just learning about ASF conventions. However, as we were proceeding with this assignment, we were performing all necessary definitions in the board_init.h, init.c and conf_board.h files. Therefore, our application code must now be cleared of the old definitions. Find the following lines of the code and remove them. You may try to build the project and follow the compilers errors. #define LED1 EXT3_PIN_7 #define LED3 EXT3_PIN_6 #define BUTTON EXT3_PIN_9 This was re-defined in the user_board.h file. void port_init(void) { struct port_config pin_conf; port_get_config_defaults(&pin_conf); /* Configure LEDs as outputs, turn them off */ pin_conf.direction = PORT_PIN_DIR_OUTPUT; port_pin_set_config(LED1, &pin_conf); port_pin_set_config(LED3, &pin_conf); /* Set buttons as inputs */ pin_conf.direction = PORT_PIN_DIR_INPUT; pin_conf.input_pull = PORT_PIN_PULL_UP; port_pin_set_config(BUTTON, &pin_conf); Customer application support in ASF – Training Manual: 9/15/2014 Page 37 of 90

Slide 41

Slide 41 text

3.1 Preliminary considerations First of all, it is an engineering reality that working with any new electronic component inevitably requires an engineer to closely inspect its datasheet. However, once we, as engineers, become familiar with the component’s operation principles, we would like to be able to merge our driver(s) seamlessly into ASF environment, without making an excessive effort to re-create those parts of ASF, which do not require to be recreated. Therefore, as a prerequisite step, it is both natural and recommended that we evaluate component’s all dependencies in terms of ASF four layers. In other words, before we begin, we should know which of ASF drivers are crucial for our component’s operation as well as which services will rely on our component. Determine, which low-level ASF drivers will be required by our custom OLED Controller component. Open the SSD1306 datasheet and learn the basic information about this component. Find out:  What protocols can be used to communicate to the device?  Which ones can be supported by our custom hardware?  Which pins are used for communication assuming 4-wire and 3-wire SPI?  Are both read and write operations allowed when using serial communication? Look at the following sections: 2. Features and 8.1.3-4 MCU Serial Interface, on pages 6 and 17, respectively. It is true that our hardware is capable of supporting both 3- and 4-wire SPI communication protocols. In this training, we will choose the 4-wire solution, as we already have our custom hardware ready. Since this option requires a combination of three SPI pins (SCLK, SDIN and CS#) with an additional pin (D/C#), it is intuitive that in ASF, we will need to find both the SPI and GPIO driver. Open ASF Wizard and add the SERCOM SPI driver in the polled API. Another driver (PORT – GPIO Pin Control) has already been added before. The two essential low-level drivers (SPI and PORT) as well as the high-level service (GFX Monochromatic) are added to our project. We have obtained a platform to create the support for our custom OLED controller (component). 3.2 Understanding and creating the file structure In Assignment 2, we discussed the benefit of having a file system, in which every file is dedicated to a specific task. In the next step, as we are going to re-create a missing layer of our component, let us consider how to organize the files in the most efficient way. Establish a file system for our component layer. Inspect the content of the following folders.  ../src/ASF/common2/  ../src/config/  ../src/ASF/common2/services/gfx_mono/ Customer application support in ASF – Training Manual: 9/15/2014 Page 41 of 90

Slide 47

Slide 47 text

Note that our header files possesses an auto-generated “wrapper”, which is a collection of consecutive #ifndef, #define, #endif statements. Their purpose is to guarantee that if a project involves several components or services that share some of the drivers, the compiler will not attempt to include the same code twice, which might result in conflicting definitions. In this file, we should also include the configuration file conf_oled_controller.h. In oled_controller.h include the configuration file: #include "conf_oled_controller.h" Since the configuration file will be used to map the board’s pins with the driver-specific pins, we must also ensure that all the definitions stored in user_board.h, init.c and conf_board.h files will be known to the driver. The simplest way to achieve this is to include the board.h file. We already know that this file acts as a “selector” for the rest of the board-related files. In conf_oled_controller.h include the board.h file. #include Last, but not least, we must also include two more files in order to make our driver work. In contrary to the SPI and PORT drivers, the fact that we need them cannot be deduced from the component’s datasheet. These two files are: compiler.h and delay.h. The first one will allow us to use variable types, such as uint8_t that are defined in Atmel Studio. The second one includes delay routines, which we will also use later. Open oled_controller.h file and add two more files: #include #include In order to compile the project, we must also add the Delay Routines service in through ASF Wizard. Using ASF Wizard, add the Delay Routines (systick) service to the project. We have created a system of files that we can use to build our custom controller on. The files are stored in accordance to ASF standard and they are mutually connected in a way that can exploit the compiler to develop the code. 3.4 Bringing datasheet into the code We can think of our component driver as a system of self-contained functions that handle data, translating the high-level graphical routines such as painting lines or displaying text with low-level commands that manipulate registers both MCU’s and component’s registers. It is solely our task to create these functions. However, before we begin constructing them, it would be practical to first create a list of definitions, which will make creating these functions an easier task. Having such commands written in our code, we begin to incorporate the component’s datasheet into the software. In a way, this is a very similar task to the one we know form Assignment 2, when we defined all pin in the user_board.h file and bring similar advantages. Customer application support in ASF – Training Manual: 9/15/2014 Page 47 of 90

Slide 48

Slide 48 text

Create a list of definitions corresponding to register-level commands applicable for our component. In order to increase the readability of our code, we will assume the following convention – all command definitions related to our new ASF component will begin with OLED_CMD_ prefix. Open the SSD1306 datasheet – 9. Command Table (pg. 28). Look at the uppermost row in the table. Define a corresponding command in the oled_controller.h file. Name the command OLED_CMD_CONTRAST_CONTROL. Remember about our convention. Since the list of all commands applicable for the driver is long, we can move forward by inserting the following block of code to the oled_controller.h file. This block contains a fundamental set of commands, based on that table in the datasheet. Note that commands related to addressing have been defined as macros in order to allow a variable parameter. /* Fundamental command definitions */ #define OLED_CMD_SET_CONTRAST_CONTROL 0x81 #define OLED_CMD_ENTIRE_DISPLAY_ON 0xA5 #define OLED_CMD_ENTIRE_DISPLAY_AND_GGDRAM_ON 0xA4 #define OLED_CMD_SET_NORMAL_DISPLAY 0xA6 #define OLED_CMD_SET_INVERSE_DISPLAY 0xA7 #define OLED_CMD_SET_DISPLAY_ON 0xAF #define OLED_CMD_SET_DISPLAY_OFF 0xAE #define OLED_CMD_SET_CHARGE_PUMP_SETTIG 0x8D /* Addressing command definitions */ #define OLED_CMD_ADDR_SET_LSB(column) (0x00 | (column)) #define OLED_CMD_ADDR_SET_MSB(column) (0x10 | (column)) #define OLED_CMD_SET_MEMORY_ADDR_MODE 0x20 #define OLED_CMD_SET_COLUMN_ADDR 0x21 #define OLED_CMD_SET_PAGE_ADDR 0x22 #define OLED_CMD_SET_PAGE_START_ADDR(page) (0xB0 | (page)) /* Hardware configuration definitions */ #define OLED_CMD_SET_DISPLAY_START_LINE(line) (0x40 | (line)) #define OLED_CMD_SET_SEGMENT_RE_MAP_COL0_SEG0 0xA0 #define OLED_CMD_SET_SEGMENT_RE_MAP_COL127_SEG0 0xA1 #define OLED_CMD_SET_MULTIPLEX_RATIO 0xA8 #define OLED_CMD_SET_OUTPUT_SCAN_UP 0xC0 #define OLED_CMD_SET_OUTPUT_SCAN_DOWN 0xC8 #define OLED_CMD_SET_DISPLAY_OFFSET 0xD3 #define OLED_CMD_SET_COM_PINS 0xDA #define OLED_CMD_SET_DISPLAY_CLOCK_DIV_RATIO 0xD5 #define OLED_CMD_SET_PRECHARGE_PERIOD 0xD9 #define OLED_CMD_SET_VCOMH_DESELECT_LVL 0xDB #define OLED_CMD_NOP 0xE3 Customer application support in ASF – Training Manual: 9/15/2014 Page 48 of 90

Slide 49

Slide 49 text

We have a basic set of commands incorporated in the code. Writing functions will now be easier, since we can more easily relate each command word to its purpose. You remember that we have isolated a specific file to store the configuration settings for our OLED controller. Create a similar list of definitions in conf_oled_controller.h. Open conf_oled_controller.h and place the following block of code there, after “#include “ directive. #define OLED_SPI #define OLED_DC_PIN #define OLED_RES_PIN #define OLED_CS_PIN #define OLED_SPI_PINMUX_SETTING #define OLED_SPI_PINMUX_PAD0 #define OLED_SPI_PINMUX_PAD1 #define OLED_SPI_PINMUX_PAD2 #define OLED_SPI_PINMUX_PAD3 #define OLED_CLOCK_SPEED 1000000UL Now, relate all these definitions with the definitions stored in the user_board.h file. This is a somewhat “mirror” process comparing to what we did in Assignment 1. In Assignment 1, we have used conf_ssd1306.h file to relate the pins and pinmux definitions to the existing component driver. Here, we do the same thing, but the other way round: we are bridging the newly defined driver’s constants with previously defined pins. Either way, this step is very important, as it allows us to separate a general component support from its physical implementation, by creating an abstraction layer. We have created definitions for the pins and SPI configuration in conf_oled_controller.h. We have also assigned these definitions (starting with OLED_) with their physical implementation at the board level (starting with DISP_).The conf_oled_controller.h should now be: #define OLED_SPI DISP_SPI #define OLED_DC_PIN DISP_CMD #define OLED_RES_PIN DISP_RES #define OLED_CS_PIN DISP_SS #define OLED_SPI_PINMUX_SETTING DISP_SPI_PINMUX_SETTINGS #define OLED_SPI_PINMUX_PAD0 DISP_SPI_PAD0 #define OLED_SPI_PINMUX_PAD1 DISP_SPI_PAD1 #define OLED_SPI_PINMUX_PAD2 DISP_SPI_PAD2 #define OLED_SPI_PINMUX_PAD3 DISP_SPI_PAD3 #define OLED_CLOCK_SPEED 1000000UL 3.5 Creating low-level set of functions Having defined the command lines, we are going to create a set of basic functions that we can use to communicate with the display controller. These functions will take care of sending basic commands and data messages to the display in a systematic fashion. The set of these functions will constitute the lower-level of Customer application support in ASF – Training Manual: 9/15/2014 Page 49 of 90

Slide 50

Slide 50 text

our driver, which will allow us to separate higher-level application oriented code from managing the component’s hardware. The first step towards constructing of the functions is to evaluate for handing of what tasks we actually need these functions for. This sounds like an obvious step; however it requires a careful analysis of both component’s datasheet and the MCU’s, as we must know of both what is possible as well as what is needed. In this Assignment, we will skip component’s support for graphics scrolling and we will concentrate on more rudimentary tasks, which will only allow the display to function. The following list presents the tasks: 1. Writing to the display controller 2. Reading from the display controller 3. Resetting 4. Enabling and disabling the sleep mode 5. Turning the display on and off 6. Setting the contrast 7. Inverting the content 8. Addressing functions 9. Initialization procedure 3.5.1 Writing to the display controller According to the datasheet, the controller distinguishes between two types of messages: data and command. This segregation suggests that we should also distinguish between these tasks in the software. Consequently, we will write two separate functions: oled_write_data and oled_write_command designed specifically to the tasks. Furthermore, we also agreed on using the 4-wire SPI protocol. In this implementation, the MCU will assume the role of a master, while the controller will act as a slave. Finally, the data-command pin (D/C#) is used to inform the controller of whether a following message should be interpreted as data or as command. In the communication process, the MCU assumes the role of a master, while the display controller acts as a slave. Create two specific functions designed to write data and command to the controller, based on the SPI protocol implementation and utilization of the D/C# pin. Open oled_controller.h file and place the following code after all definitions. extern struct spi_module oled_master; extern struct spi_slave_inst oled_slave; // OLED controller write and read functions void oled_write_command(uint8_t command); void oled_write_data(uint8_t data); Open oled_controller.c file and place the following code after all definitions. struct spi_module oled_master; struct spi_slave_inst oled_slave; void oled_write_command(uint8_t command) { } Customer application support in ASF – Training Manual: 9/15/2014 Page 50 of 90

Slide 51

Slide 51 text

void oled_write_data(uint8_t data) { } What we just did is a part of using a module. Although we will leave the initialization procedure until the end of this section, we do define two structures related to the two SPI module that will be used to  store module configuration settings (oled_master)  store information about the status of the SPI slave – display controller (oled_slave). On top of that, we declare the structures as extern in the header file in order to make them accessible within the entire project, which is essential if we are going to expand it by connecting more slaves. Knowing about D/C# pin role and the SPI configuration needed, create the body of the two functions. The D/C# options are explained in the SSD1306 datasheet on page 17. The SPI configuration is explained in ASF Quick Start Guide (workflow). The resulting functions should look like this: void oled_write_command(uint8_t command) { spi_select_slave(&oled_master, &oled_slave, true); port_pin_set_output_level(OLED_DC_PIN, false); spi_write_buffer_wait(&oled_master, &command, 1); spi_select_slave(&oled_master, &oled_slave, false); } void oled_write_data(uint8_t data) { spi_select_slave(&oled_master, &oled_slave, true); port_pin_set_output_level(OLED_DC_PIN, true); spi_write_buffer_wait(&oled_master, &data, 1); spi_select_slave(&oled_master, &oled_slave, false); } The procedure can be summarized as follows:  Select a slave – “oled_slave” in our case  Set the correct D/C# pin level, depending on the type of message  Write the message (“1” refers to the length of the buffer array, which is just single word in our case)  Deselect the slave. 3.5.2 Reading from the display controller According to the SSD1306 datasheet, reading operations are not supported under serial communication protocols, which mean we could in principle skip the reading instructions. However, since our driver might be used by someone else in the future, it would be preferable to create “null” functions in order to make the code self consistent and more consciously convey the message. Although the functions are forced to return “zero”, Customer application support in ASF – Training Manual: 9/15/2014 Page 51 of 90

Slide 52

Slide 52 text

having them in any way defined in the code, we avoid a certain risk of misunderstanding of what happens if reading from the controller is requested by any fragment of the application. Open oled_controller.h file and place the following code: // Read data from the controller - NOT SUPPORTED static inline uint8_t oled_read_data(void) { return 0; } // Read status from the controller - NOT SUPPORTED static inline uint8_t oled_get_status(void) { return 0; } We have defined data and command reading instructions. Usage of the keyword inline is optional. However, since we are dealing with small functions that will be called frequently, it is recommended to use this keyword. What it does it simply replaces the body of the function with actual code, making a positive impact on the device’s speed. 3.5.3 Resetting of the display Another important function is a resetting procedure, which will allow our application to restart the device without the necessity to power down the entire hardware. Create a resetting function. Open the SSD1306 datasheet and look through section “8.9 Power ON and OFF sequence”. Understand the timing diagram. What is the minimal recommended waiting period related to RES# pin? Define the following function in the oled_controller.h file. // Reset the OLED controller by setting the reset pin low. static inline void oled_hard_reset(void) { uint32_t delay_10us = 10 * (system_gclk_gen_get_hz(0)/1000000); port_pin_set_output_level(OLED_RES_PIN, false); delay_cycles(delay_10us); // At least 10us port_pin_set_output_level(OLED_RES_PIN, true); delay_cycles(delay_10us); // At least 10us } Here, the system_gclk_gen_get_hz(0) function is used to calibrate the delay, taking “0” as argument, which refers to the Generic Clock #0 – the main CPU clock. Observe that in this function we use delay_cycles() function that is provided by the Delay Routines (service), which we have added earlier in the Assignment. We did it then just to show a consistent picture of dependencies. However, when developing a new driver it might be not obvious from the start, which drivers we need in addition. That is why it is useful to remember that we can use ASF Wizard anytime during the development process. Customer application support in ASF – Training Manual: 9/15/2014 Page 52 of 90

Slide 53

Slide 53 text

We have defined a reset function. 3.5.4 Enabling and disabling the display Sometimes we may need to enable a sleep mode operation in order to, for example, reduce the power consumption. It is, therefore, practical to define the sleep enable and disable functions. Create functions to sleep enable and disable the display controller. Look into section 10.1.12 Set display ON/OFF in SSD1306 datasheet. Define the following functions in oled_controller.h file. // Enable the OLED sleep mode static inline void oled_sleep_enable(void) { oled_write_command(OLED_CMD_SET_DISPLAY_OFF); } // Disable the OLED sleep mode static inline void oled_sleep_disable(void) { oled_write_command(OLED_CMD_SET_DISPLAY_ON); } Sleep enable and disable functions are created. 3.5.5 Turning the display on and off In similar fashion to enabling and disabling of the module, we may want to turn it off completely. In case of SSD1306, there exists no specific sleep mode and therefore, disabling of the display will be equivalent to turning the entire device off in our case. From the software side, however, enabling sleep mode and disabling a device completely might not mean the same thing in general, and we should therefore reflect that in our code. Create functions to enable and disable the display controller, similar to the previous two. Define the following functions in oled_controller.h file. // Enable the OLED sleep mode static inline void oled_display_on(void) { oled_write_command(OLED_CMD_SET_DISPLAY_ON); } // Disable the OLED sleep mode static inline void oled_display_off(void) { oled_write_command(OLED_CMD_SET_DISPLAY_OFF); } Display enable and disable functions are created, which contain the same instructions as their sleep enable/disable counterparts. 3.5.6 Setting contrast Another aspect of manipulating of the display is to set its contrast value. Customer application support in ASF – Training Manual: 9/15/2014 Page 53 of 90

Slide 54

Slide 54 text

Create functions to set contrast level for the display. The SSD1306 controller possesses 256 contrast levels (0x00-0xFF), which can be set after sending a command word 0x81. Look at section 10.1.7 in SSD1306 datasheet. Define the following functions in oled_controller.h file. static inline uint8_t oled_set_contrast(uint8_t contrast) { oled_write_command(OLED_CMD_SET_CONTRAST_CONTROL); oled_write_command(contrast); return contrast; } We have defined a contrast setting function. 3.5.7 Inverting the content Another practical function is the possibility to invert an image on the display in terms of colors (black and white in our case). This option is supported by the component’s hardware and it does not cost us much to implement it in the software. Create a set of functions to invert and restore the image. Place the following instructions in oled_controller.h file. static inline void oled_display_invert_enable(void) { oled_write_command(OLED_CMD_SET_INVERSE_DISPLAY); } static inline void oled_display_invert_disable(void) { oled_write_command(OLED_CMD_SET_NORMAL_DISPLAY); } We added the possibility for inverting the image. 3.5.8 Addressing functions Finally, we need to construct three functions that will help us to manage addressing of pixel positions on the display screen. According to the datasheet (sec. 10.1.3), the display controller allows using three addressing modes and it up to us which one to choose. If we intend to focus on efficiency, we should adapt either vertical or horizontal addressing mode as they require less operations to be performed by our software. On the other hand, page addressing mode is often the only mode supported by other controllers and choosing this one offers our code greater flexibility. (In this project we will choose the page addressing mode.) Addressing space of the display is organized the way that follows the controller’s Graphic Display Data RAM (GDDRAM). It is divided into so-called pages and columns (fig. 3-7) defined as:  page, which is an 8-bit high row, counting from zero, which is the uppermost one.  column, which is the position of the 8-bit word counting from the left. Therefore, in the memory map, the position of each pixel is defined through three parameters: page, column and the pixel’s position within the column. However, since we are going to send bytes to GDDRAM instead of bits, each pixel’s position becomes an implicit property of a byte that contains it. Consequently, we will only need to explicitly specify addresses the two first parameters. Customer application support in ASF – Training Manual: 9/15/2014 Page 54 of 90

Slide 56

Slide 56 text

We have defined a function to specify the page. Now, look into sections 10.1.1 and 10.1.2. When using the page addressing mode, the column addressing routine depends on whether we target the lower or the upper nibble of the column addressing space. Therefore we need to take this fact into account in our function. We will do that by referring to the following macros defined earlier: #define OLED_CMD_ADDR_SET_LSB(column) (0x00 | (column)) #define OLED_CMD_ADDR_SET_MSB(column) (0x10 | (column)) Define the following function in oled_controller.h file. static inline void oled_set_column_address(uint8_t address) { // Make sure the address is 7 bits address &= 0x7F; oled_write_command(OLED_CMD_ADDR_SET_MSB(address >> 4)); oled_write_command(OLED_CMD_ADDR_SET_LSB(address & 0x0F)); } We have defined a function to specify the column. Finally, look into section 10.1.6. In order to build a line addressing function, we use the following macro and mask the bits in similar fashion. #define OLED_CMD_SET_DISPLAY_START_LINE(line) (0x40 | (line)) Define the following function in oled_controller.h file. static inline void oled_set_display_start_line_address(uint8_t address) { // Make sure address is 6 bits address &= 0x3F; oled_write_command(OLED_CMD_SET_DISPLAY_START_LINE(address)); } We have defined a function to specify the starting line. The list of fundamental driver functions is now nearly complete. So far, apart from scrolling, we have defined all necessary routines to make our display fulfill its functions low-level functions such as adjusting contrast, managing addressing or enforcing reset. What still remains at this level is a proper initialization of the device, which will be discussed in the next section. 3.6 Initialization procedure Defining proper initialization routines is an essential step to ensure correct operation of the controller. Although in the program flow all initialization commands are executed first, in the process of building of the code, we have decided to define them now, after we have declared other functions and definitions. Since we are dealing with an external device, our initialization routines will ensure the correct settings of both: MCU’s peripheral modules and external component’s registers. For this reason, it is logical to split the initialization code into two functions:  oled_inerface_init() that will initialize all the internal MCU’s modules used for communicating to the component, and… Customer application support in ASF – Training Manual: 9/15/2014 Page 56 of 90

Slide 57

Slide 57 text

 oled_init() that will use the interface and set up all the controller’s registers that are external to the MCU. 3.6.1 Internal initialization As discussed earlier, our controller needs two modules to communicate with. The SERCOM SPI will be used to send commands and data to the component using serial data-in (SDIN), serial clock (SCLK) and chip select (CS#) pins, while PORT will allow us to use GPIO pins to reset (RES) and switch between commands and data messages (D/C#). Create oled_interface_init() function to configure and enable SPI and PORT modules. Recall the standard procedure for configuring peripheral modules using Atmel Studio for SAM-D device family. Open oled_controller.c file and begin to define the function with the following code: static void oled_interface_init(void) { struct spi_config config; struct spi_slave_inst_config slave_config; } The two local structures will be used to store the configuration settings for the SPI module and to hold the instance of the SPI slave (display controller in our case). We will configure the slave first. Place the following code into the function. spi_slave_inst_get_config_defaults(&slave_config); slave_config.ss_pin = OLED_CS_PIN; spi_attach_slave(&oled_slave, &slave_config); Our slave will use the default configuration. It will also be assigned the chip select pin that we use in our hardware. Similarly, we will configure the MCU as an SPI master. Place the following code further into the function: spi_get_config_defaults(&config); config.mux_setting = OLED_SPI_PINMUX_SETTING; config.pinmux_pad0 = OLED_SPI_PINMUX_PAD0; config.pinmux_pad1 = OLED_SPI_PINMUX_PAD1; config.pinmux_pad2 = OLED_SPI_PINMUX_PAD2; config.pinmux_pad3 = OLED_SPI_PINMUX_PAD3; config.mode_specific.master.baudrate = OLED_CLOCK_SPEED; spi_init(&oled_master, OLED_SPI, &config); spi_enable(&oled_master); Here we define the pin (and pinmux) configurations that the MCU will use to communicate to the controller. The two last lines in the block assign our SERCOM#1 module to handle the communication and enable the module as a whole. Customer application support in ASF – Training Manual: 9/15/2014 Page 57 of 90

Slide 58

Slide 58 text

Finally, we need to add the “PORT-related” part of the configuration. Place the following code into the function. struct port_config pin; port_get_config_defaults(&pin); pin.direction = PORT_PIN_DIR_OUTPUT; port_pin_set_config(OLED_DC_PIN, &pin); port_pin_set_config(OLED_RES_PIN, &pin); Our module interface is now configured correctly, by assigning master’s role to the MCU and the CS# pin for the slave. It also ensures that the D/C# and RES pins are configured as output. 3.6.2 External initialization The initialization of the display controller is the second step as it requires both the knowledge about the component (datasheet) and the proper configurations of the internal MCU’s modules. Create oled_init() function to configure the display controller hardware Open oled_controller.h file and place the declaration of oled_init function just before the #endif statement: void oled_init(void); Open oled_controller.c file and begin to define the function with the following code: void oled_init(void) { // Initialize delay routine – required for oled_hard_reset() delay_init(); // Do a hard reset of the OLED display controller oled_hard_reset(); // Initialize the interface oled_interface_init(); // Set the reset pin to the default state port_pin_set_output_level(OLED_RES_PIN, true); } This is necessary minimum that needs to be done in order to configure the controller. Section 8.5 in the datasheet explains the default configurations that are enforced on the display upon resetting, which is exactly what we do in this code. As engineers, however, we may be concerned about other issues such as power consumption or refresh rate of the display. Therefore, it is our task is to make decisions about what specific configurations we desire for our application and the initialization function is the right place to perform these settings. On the other hand, since the aim for this training is to teach ASF-related processes rather than discuss component-specific details; let us simply agree on certain settings that work well with our application. All in all, the component’s datasheet will be the ultimate source of information regarding these settings. From the software perspective, the initialization function is the most legitimate place to perform the settings. Customer application support in ASF – Training Manual: 9/15/2014 Page 58 of 90

Slide 61

Slide 61 text

Figure 3.7.1.1.1. File structure of the GFX Monochrome service in context of our application. The red letters and the red arrow between the gfx_mono_null.h and oled_controller.h files represent the required “link” between the service and the component layers, which is a part of the customization process. Figure 3-8. presents an excerpt of the file structure of our project. OLED Controller component layer consists of 3 files and all of them are now complete. The GFX Monochrome service is consisted of 11 files that are stored under “../src/ASF/common2/services/gfx_mono” folder. Fortunately, we do not need to change all of them, but before we proceed, let us discuss their purpose one by one. 1. gfx_mono.h – this file provides few most general macros that are common for the entire service. We do not need to change it. 2. SYSFONT – this is a sub-service of GFX Monochrome that provides text and font specific definitions. It is consisted of: gfx_mono_text.h (and .c) and sysfont.h (and .c). None of them we need to change. 3. gfx_mono_generic.h (.c) – these files provide definitions and functions used to manipulate graphics, such as drawing of lines, circles and rectangles. They are called generic and all of these routines are independent on a particular choice of display controller. Because of that, we do not need to change them. 4. gfx_mono_framebuffer.h (.c) – these files provide definitions and functions related to reading, writing from/to a so-called framebuffer. The framebuffer is a screen representation in RAM that can be thought of as a virtual display, which allows manipulating of data on pixel level. In some cases it is an optional aid to handle graphics. However, in cases when reading from the display is prohibited, it is an essential tool that provides the driver integrity. Again, we do not need to change them. Customer application support in ASF – Training Manual: 9/15/2014 Page 61 of 90

Slide 62

Slide 62 text

5. gfx_mono_null.h (.c) – these are files contain reading and writing definitions in context that is specific to a custom display and as such we will need to change them. The exact name “gfx_mono_null” is a consequence of selecting the null display earlier in the exercise. If we specified ug_2832hsweg04 as in Assignment 1, the name would read “gfx_mono_ug_2832hsweg04” and it would contain the accurate definitions for that display – similar for other displays. At this stage, we could ask why we do select null display? The answer is two-fold:  This choice allows us to use nearly 100% of the GFX Monochrome service.  It provides us with a possibility to more intuitively configure the service thanks to a virtual display support (null). As we are building the support for a custom display, perhaps a more intuitive approach would be to create two empty files and write them in a way similar to gfx_mono_ug_2832hsweg04.h/c, but tailored to support our custom component. This solution would work, but it would certainly be time consuming, as we would be left without any clues about how to properly write these files. On the other hand, by selecting null display we obtain a set of “nearly ready” files that already contain some useful definitions. Generated automatically, they all define routines to support of a virtual display, redirecting all read and write functions to virtual framebuffer. If we use them consciously, we can change some of these definitions to support functions that are relevant for our real display. We can also leave those definitions, which are not supported by it (e.g. reading from the display in our case) and hence preserve the code integrity. Our changes will therefore be less invasive and the development process more efficient. 3.7.2 Switching the points We have agreed that we would use the null display as a starting point for the application. If we look into the gfx_mono_null.h file, we will notice that it contains nothing more, but a list of definitions. Starting with few “global” definitions describing key constants such as LCD width and high in pixels, its body is essentially a list of high-level general GFX functions defined through lower-level functions that are specific to the implementation. We can divide these definitions into two groups: 1. Defined through gfx_mono_generic functions, which are:  _draw_horizontal_line  _draw_vertical_line  _draw_line  _draw_rect  _draw_filled_rect  _draw_circle  _draw_filled_circle  _put_bitmap 2. Defined through gfx_mono_framebuffer functions, which are:  _draw_pixel  _get_pixel  _put_page  _get_page  _put_byte Customer application support in ASF – Training Manual: 9/15/2014 Page 62 of 90

Slide 63

Slide 63 text

 _get_byte  _mask_byte The first group does not need our involvement, as all of the functions are not specific to any component. The second group, however, contains the functions that we need to work with. As you can see, they are all defined through the framebuffer, which makes the project compile. However, as we wish to make the GFX Monochrome service to work with our component, we will need to create custom definitions for these functions. By doing this we will create the missing link between the OLED controller component and GFX Monochrome service. Re-define all framebuffer-based functions, by “switching the points” in the gfx_mono_null.h file and creating their respective definitions in gfx_mono_null.c file. Open gfx_mono_null.h file and add the following #include statement in the beginning of the file that will enable us access to all definitions created in the component layer. #include "oled_controller.h" Change the gfx_mono_draw_pixel function in gfx_mono_null.h file by using the following code: #define gfx_mono_draw_pixel(x, y, color) \ gfx_mono_oled_draw_pixel(x, y, color) //gfx_mono_framebuffer_draw_pixel(x, y, color) Create a declaration of this function in the end of the gfx_mono_null.h file (before the #endif statement). /* declarations */ void gfx_mono_oled_draw_pixel(gfx_coord_t x,gfx_coord_t y,gfx_mono_color_t color); In gfx_mono_null.c file create the respective definition of this function: void gfx_mono_oled_draw_pixel(gfx_coord_t x, gfx_coord_t y, gfx_coord_t color) { uint8_t page; uint8_t pixel_mask; uint8_t pixel_value; /* Discard pixels drawn outside the screen */ if ((x > GFX_MONO_LCD_WIDTH - 1) || (y > GFX_MONO_LCD_HEIGHT - 1)) { return; } page = y / GFX_MONO_LCD_PIXELS_PER_BYTE; pixel_mask = (1 << (y - (page * 8))); /* * Read the page containing the pixel in interest, then perform the * requested action on this pixel before writing the page back to the * display. */ pixel_value = gfx_mono_get_byte(page, x); switch (color) { case GFX_PIXEL_SET: pixel_value |= pixel_mask; Customer application support in ASF – Training Manual: 9/15/2014 Page 63 of 90

Slide 64

Slide 64 text

break; case GFX_PIXEL_CLR: pixel_value &= ~pixel_mask; break; case GFX_PIXEL_XOR: pixel_value ^= pixel_mask; break; default: break; } gfx_mono_put_byte(page, x, pixel_value); } This function draws a pixel, whose position is defined through x- and y-coordinates. Depending on the color choice, it adds, removes or toggles the pixel. Note that the definition of this function is nearly identical to the corresponding definition placed in gfx_mono_framebuffer.c file, except for that it also changes the dependencies – instead of using the framebuffer, we use “oled” that represents our custom component. (1 out of 7) framebuffer functions is redefined for our custom OLED controller. Change the gfx_mono_get_byte function in gfx_mono_null.h file by using the following code: #define gfx_mono_get_byte(page, column) \ gfx_mono_oled_get_byte(page, column) //gfx_mono_framebuffer_get_byte(page, column) Create a declaration of this function in the end of the gfx_mono_null.h file (before the #endif statement). uint8_t gfx_mono_oled_get_byte(gfx_coord_t page, gfx_coord_t column); In gfx_mono_null.c file create the respective definition of this function. uint8_t gfx_mono_oled_get_byte(gfx_coord_t page, gfx_coord_t column) { #ifdef CONFIG_OLED_FRAMEBUFFER return gfx_mono_framebuffer_get_byte(page, column); #else oled_set_page_address(page); oled_set_column_address(column); return oled_read_data(); #endif } As stated in the SSD1306 datasheet, reading from the display is not possible under serial communication protocol. For this reason, we will stay with the framebuffer solution. However, since we are working with the service layer now, it would be desirable to make our changes “open”, such that our code will still work if we decide to use parallel communication interface at some point. Because of that we add the {#ifdef, #else, #endif} statements. Note that, although we will still be using the framebuffer in this project, we already start to use functions from the component layer. Customer application support in ASF – Training Manual: 9/15/2014 Page 64 of 90

Slide 65

Slide 65 text

We have implicitly assumed to have the CONFIG_OLED_FRAMEBUFFER flag defined. In fact, do not have it defined! Open conf_oled_controller.h file and add this flag: #define CONFIG_OLED_FRAMEBUFFER 2 (out of 7) framebuffer functions is redefined for our custom OLED controller. Change the gfx_mono_put_byte function in gfx_mono_null.h file by using the following code: #define gfx_mono_put_byte(page, column, data) \ gfx_mono_oled_put_byte(page, column, data, false) //gfx_mono_framebuffer_put_byte(page, column, data) Create a declaration of this function in the end of the gfx_mono_null.h file (before the #endif statement). void gfx_mono_oled_put_byte(gfx_coord_t page, gfx_coord_t column, uint8_t data, bool force); In gfx_mono_null.c file create the respective definition of this function. void gfx_mono_oled_put_byte(gfx_coord_t page, gfx_coord_t column, uint8_t data, bool force) { #ifdef CONFIG_OLED_FRAMEBUFFER if (!force && data == gfx_mono_framebuffer_get_byte(page, column)) { return; } gfx_mono_framebuffer_put_byte(page, column, data); #endif oled_set_page_address(page); oled_set_column_address(column); oled_write_data(data); } At this stage, we need to ensure that what we write to the display, we write to the framebuffer as well. This is extremely important, since it is only possible to read from the framebuffer. Skipping this step will make the data stored in GDDRAM of the display controller inconsistent with the framebuffer, which will result in errors. Furthermore, since our function will perform writing to both places, one more option has been added. By using of a flag (force), it is possible to decide if we want to force writing to the framebuffer or let us check first if the new data is different from the old data, and possibly skip this step when they are the same. Generally speaking, if the CPU power is a limiting factor, we will most likely try to check first (not forcing). For a change, if the MCU-LCD communication speed is a limiting factor, it makes sense simplify the code (forcing). Customer application support in ASF – Training Manual: 9/15/2014 Page 65 of 90

Slide 66

Slide 66 text

3 (out of 7) framebuffer functions is redefined for our custom OLED controller. Change the gfx_mono_get_pixel function in gfx_mono_null.h file by using the following code: #define gfx_mono_get_pixel(page, column) \ gfx_mono_oled_get_pixel(page, column) //gfx_mono_framebuffer_get_pixel(page, column) Create a declaration of this function in the end of the gfx_mono_null.h file (before the #endif statement). uint8_t gfx_mono_oled_get_pixel(gfx_coord_t x, gfx_coord_t y); In gfx_mono_null.c file create the respective definition of this function (in similar way to the framebuffer function definition). uint8_t gfx_mono_oled_get_pixel(gfx_coord_t x, gfx_coord_t y) { uint8_t page; uint8_t pixel_mask; if ((x > GFX_MONO_LCD_WIDTH - 1) || (y > GFX_MONO_LCD_HEIGHT - 1)) { return 0; } page = y / GFX_MONO_LCD_PIXELS_PER_BYTE; pixel_mask = (1 << (y - (page * 8))); return gfx_mono_get_byte(page, x) & pixel_mask; } 4 (out of 7) framebuffer functions is redefined for our custom OLED controller. Change the gfx_mono_put_page function in gfx_mono_null.h file by using the following code: #define gfx_mono_put_page(data, page, column, width) \ gfx_mono_oled_put_page(data, page, column, width) //gfx_mono_framebuffer_put_page(data, page, column, width) Create a declaration of this function in the end of the gfx_mono_null.h file (before the #endif statement). void gfx_mono_oled_put_page(gfx_mono_color_t *data, gfx_coord_t page, gfx_coord_t page_offset, gfx_coord_t width); In gfx_mono_null.c file create the respective definition of this function. void gfx_mono_oled_put_page(gfx_mono_color_t *data, gfx_coord_t page, gfx_coord_t column, gfx_coord_t width) { #ifdef CONFIG_OLED_FRAMEBUFFER gfx_mono_framebuffer_put_page(data, page, column, width); #endif oled_set_page_address(page); oled_set_column_address(column); Customer application support in ASF – Training Manual: 9/15/2014 Page 66 of 90

Slide 77

Slide 77 text

# define CONF_CLOCK_GCLK_3_PRESCALER 30 # define CONF_CLOCK_GCLK_3_OUTPUT_ENABLE false Appendix B. Complete customized component files B.1 The body of the oled_controller.h file: #ifndef OLED_CONTROLLER_H_ #define OLED_CONTROLLER_H_ #include #include #include #include #include "conf_oled_controller.h" /* Fundamental command definitions */ #define OLED_CMD_SET_CONTRAST_CONTROL 0x81 #define OLED_CMD_ENTIRE_DISPLAY_ON 0xA5 #define OLED_CMD_ENTIRE_DISPLAY_AND_GGDRAM_ON 0xA4 #define OLED_CMD_SET_NORMAL_DISPLAY 0xA6 #define OLED_CMD_SET_INVERSE_DISPLAY 0xA7 #define OLED_CMD_SET_DISPLAY_ON 0xAF #define OLED_CMD_SET_DISPLAY_OFF 0xAE /* Addressing command definitions */ #define OLED_CMD_ADDR_SET_LSB(column) (0x00 | (column)) #define OLED_CMD_ADDR_SET_MSB(column) (0x10 | (column)) #define OLED_CMD_SET_MEMORY_ADDR_MODE 0x20 #define OLED_CMD_SET_COLUMN_ADDR 0x21 #define OLED_CMD_SET_PAGE_ADDR 0x22 #define OLED_CMD_SET_PAGE_START_ADDR(page) (0xB0 | (page)) /* Hardware configuration definitions */ #define OLED_CMD_SET_DISPLAY_START_LINE(line) (0x40 | (line)) #define OLED_CMD_SET_SEGMENT_RE_MAP_COL0_SEG0 0xA0 #define OLED_CMD_SET_SEGMENT_RE_MAP_COL127_SEG0 0xA1 #define OLED_CMD_SET_MULTIPLEX_RATIO 0xA8 #define OLED_CMD_SET_OUTPUT_SCAN_UP 0xC0 #define OLED_CMD_SET_OUTPUT_SCAN_DOWN 0xC8 #define OLED_CMD_SET_DISPLAY_OFFSET 0xD3 #define OLED_CMD_SET_COM_PINS 0xDA #define OLED_CMD_SET_DISPLAY_CLOCK_DIV_RATIO 0xD5 #define OLED_CMD_SET_PRECHARGE_PERIOD 0xD9 #define OLED_CMD_SET_VCOMH_DESELECT_LVL 0xDB #define OLED_CMD_NOP 0xE3 #define OLED_CMD_SET_CHARGE_PUMP_SETTIG 0x8D extern struct spi_module oled_master; extern struct spi_slave_inst oled_slave; // OLED controller write and read functions void oled_write_command(uint8_t command); void oled_write_data(uint8_t data); // Read data from the controller - NOT SUPPORTED Customer application support in ASF – Training Manual: 9/15/2014 Page 77 of 90

Slide 80

Slide 80 text

spi_init(&oled_master, OLED_SPI, &config); spi_enable(&oled_master); struct port_config pin; port_get_config_defaults(&pin); pin.direction = PORT_PIN_DIR_OUTPUT; port_pin_set_config(OLED_DC_PIN, &pin); port_pin_set_config(OLED_RES_PIN, &pin); } void oled_init(void) { // Initialize delay routine – required for oled_hard_reset() delay_init(); // Do a hard reset of the OLED display controller oled_hard_reset(); // Initialize the interface oled_interface_init(); // Set the reset pin to the default state port_pin_set_output_level(OLED_RES_PIN, true); // 1/32 Duty (0x0F~0x3F) oled_write_command(OLED_CMD_SET_MULTIPLEX_RATIO); oled_write_command(0x1F); // Shift Mapping RAM Counter (0x00~0x3F) oled_write_command(OLED_CMD_SET_DISPLAY_OFFSET); oled_write_command(0x00); // Set Mapping RAM Display Start Line (0x00~0x3F) oled_write_command(OLED_CMD_SET_DISPLAY_START_LINE(0x00)); // Set Column Address 0 Mapped to SEG0 oled_write_command(OLED_CMD_SET_SEGMENT_RE_MAP_COL127_SEG0); // Set COM/Row Scan Scan from COM63 to 0 oled_write_command(OLED_CMD_SET_OUTPUT_SCAN_DOWN); // Set COM Pins hardware configuration oled_write_command(OLED_CMD_SET_COM_PINS); oled_write_command(0x02); oled_set_contrast(0x8F); // Disable Entire display On oled_write_command(OLED_CMD_ENTIRE_DISPLAY_AND_GGDRAM_ON); oled_display_invert_disable(); // Set Display Clock Divide Ratio / Oscillator Frequency (Default => 0x80) oled_write_command(OLED_CMD_SET_DISPLAY_CLOCK_DIV_RATIO); oled_write_command(0x80); // Enable charge pump regulator oled_write_command(OLED_CMD_SET_CHARGE_PUMP_SETTIG); oled_write_command(0x14); // Set VCOMH Deselect Level oled_write_command(OLED_CMD_SET_VCOMH_DESELECT_LVL); oled_write_command(0x40); // Default => 0x20 (0.77*VCC) // Set Pre-Charge as 15 Clocks & Discharge as 1 Clock oled_write_command(OLED_CMD_SET_PRECHARGE_PERIOD); oled_write_command(0xF1); oled_display_on(); } B.3 The body of the conf_oled_controller.c file: #ifndef CONF_OLED_CONTROLLER_H_ #define CONF_OLED_CONTROLLER_H_ Customer application support in ASF – Training Manual: 9/15/2014 Page 80 of 90

Slide 82

Slide 82 text

#define gfx_mono_draw_line(x1, y1, x2, y2, color) \ gfx_mono_generic_draw_line(x1, y1, x2, y2, color) #define gfx_mono_draw_rect(x, y, width, height, color) \ gfx_mono_generic_draw_rect(x, y, width, height, color) #define gfx_mono_draw_filled_rect(x, y, width, height, color) \ gfx_mono_generic_draw_filled_rect(x, y, width, height, \ color) #define gfx_mono_draw_circle(x, y, radius, color, octant_mask) \ gfx_mono_generic_draw_circle(x, y, radius, color, \ octant_mask) #define gfx_mono_draw_filled_circle(x, y, radius, color, quadrant_mask) \ gfx_mono_generic_draw_filled_circle(x, y, radius, \ color, quadrant_mask) #define gfx_mono_put_bitmap(bitmap, x, y) \ gfx_mono_generic_put_bitmap(bitmap, x, y) #define gfx_mono_draw_pixel(x, y, color) \ gfx_mono_oled_draw_pixel(x, y, color) //gfx_mono_framebuffer_draw_pixel(x, y, color) #define gfx_mono_get_byte(page, column) \ gfx_mono_oled_get_byte(page, column) //gfx_mono_framebuffer_get_byte(page, column) #define gfx_mono_init() \ gfx_mono_oled_init() //gfx_mono_null_init() #define gfx_mono_put_page(data, page, column, width) \ gfx_mono_oled_put_page(data, page, column, width) //gfx_mono_framebuffer_put_page(data, page, column, width) #define gfx_mono_get_page(data, page, column, width) \ gfx_mono_oled_get_page(data, page, column, width) //gfx_mono_framebuffer_get_page(data, page, column, width) #define gfx_mono_put_byte(page, column, data) \ gfx_mono_oled_put_byte(page, column, data, false) //gfx_mono_framebuffer_put_byte(page, column, data) #define gfx_mono_get_pixel(page, column) \ gfx_mono_oled_get_pixel(page, column) //gfx_mono_framebuffer_get_pixel(page, column) #define gfx_mono_mask_byte(page, column, pixel_mask, color) \ gfx_mono_oled_mask_byte(page, column, pixel_mask, color) //gfx_mono_framebuffer_mask_byte(page, column, pixel_mask, color) #define gfx_mono_put_framebuffer() \ ; void gfx_mono_oled_init(void); Customer application support in ASF – Training Manual: 9/15/2014 Page 82 of 90

Slide 87

Slide 87 text

adc_enable_callback(&adc_instance, ADC_CALLBACK_READ_BUFFER); } Obviously, in order for the module to operate correctly, we need to define the body of the callback function as well as call the initialization function (light_sensor_init(); in our case) in the main program. D.2 The meaning of module instance and config struct’s. The ASF 3.0 convention predicts the existence of two kinds of structures: instances and configurations. Understating of their purpose is essential, if we wish to effectively and consciously use the ASF drivers. Instances are the first group of structures, whose purpose is to represent hardware peripheral modules in software. In order for the drivers to work correctly, they must be “linked” to physical modules they intend to operate on. The corresponding software structures are the collection of parameters describing the status of the modules under operation. These parameters could be, for example, a buffer containing data received through UART, a list of slaves assigned to a SPI master or an array of samples converted using ADC. The practical aspect of instances is easy to understand given the following example: let us assume that our application uses two SERCOM modules to communicate to two external units using USART. Naturally, we can use the SERCOM-USART driver available in ASF to handle this communication. However, without two separate instances representing to each SERCOM, the driver would not know which one of them is, for example, ready to ready data or which data buffer belongs to the particular module. Having the two instances we obtain a unique representation of the hardware and still able to use a single driver. Because instances represent the hardware modules that are in use, the corresponding structures should be declared as global. Especially, when a project is distributed over several files, we should make sure that instances are available to every function declared in the main program. In our case, our code involves a structure adc_instance of the adc_module type that is declared in main.c file outside any function. Configurations (or configs) are another kind of structures used in ASF. They are created to facilitate initializations and configurations of peripheral modules. Here, we are using config_adc of type adc_config, declared as local variable to the light_sensor_init(); function. It contains all the relevant parameters, whose definitions are needed to make the module operational. In contrary to instances, the config structures can be declared as either local or global and it depends on the character of an application which one we should choose. In principle, when a variable is declared locally memory spaced used to contain it is freed as soon as a corresponding function’s execution is finished. Consequently, if our application requires that a module is configured once (e.g. at the beginning of the program) and stays “unchanged”, it makes more sense to save memory by declaring the config structure locally. In some applications, however, it may be required that a module is reconfigured several times during the program execution. In these cases, it would be favorable to declare a global configuration structure and let the program use a fixed memory resource instead of dynamically allocate space at every occurrence of re- configuration. At this stage, you can observe that the link between the temporarily existing configuration structure and a “permanent” module instance is created by performing step #4 in the initialization process: adc_init(&adc_instance, ADC, &config_adc); In general, usage of structs for module configuration is a differentiating feature of ASF 3.0. It allows us – as users – to abstract from the register level code and memory maps and work with more user-friendly APIs. Instead of using arrays representing the registers and pointers to “navigate” over them, we can use config structures to more easily manipulate the settings and declare specific actions based on changes to instance structures, when necessary. This makes the code more transparent to the user and, at the same time, facilitates its portability. Customer application support in ASF – Training Manual: 9/15/2014 Page 87 of 90

Slide 90

Slide 90 text

Customer application support in ASF – Training Manual: 9/15/2014 Page 90 of 90 Atmel Corporation 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 │ www.atmel.com © 2014 Atmel Corporation. / Rev.: Error: Reference source not found – Training Manual: 9/15/2014. Atmel®, Atmel logo and combinations thereof, Enabling Unlimited Possibilities®, and others are registered trademarks or trademarks of Atmel Corporation in U.S. and other countries. ARM®, ARM Connected® logo, and others are the registered trademarks or trademarks of ARM Ltd. Other terms and product names may be trademarks of others. DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life. SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any applications where the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without an Atmel officer's specific written consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for the operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in military or aerospace applications or environments unless specifically designated by Atmel as military-grade. Atmel products are not designed nor intended for use in automotive applications unless specifically designated by Atmel as automotive-grade.

Slide 1

Slide 1 text

Slide 2

Slide 2 text

Slide 3

Slide 3 text

Slide 4

Slide 4 text

Slide 5

Slide 5 text

Slide 6

Slide 6 text

Slide 7

Slide 7 text

Slide 8

Slide 8 text

Slide 9

Slide 9 text

Slide 10

Slide 10 text

Slide 11

Slide 11 text

Slide 12

Slide 12 text

Slide 13

Slide 13 text

Slide 14

Slide 14 text

Slide 15

Slide 15 text

Slide 16

Slide 16 text

Slide 17

Slide 17 text

Slide 18

Slide 18 text

Slide 19

Slide 19 text

Slide 20

Slide 20 text

Slide 21

Slide 21 text

Slide 22

Slide 22 text

Slide 23

Slide 23 text

Slide 24

Slide 24 text

Slide 25

Slide 25 text

Slide 26

Slide 26 text

Slide 27

Slide 27 text

Slide 28

Slide 28 text

Slide 29

Slide 29 text

Slide 30

Slide 30 text

Slide 31

Slide 31 text

Slide 32

Slide 32 text

Slide 33

Slide 33 text

Slide 34

Slide 34 text

Slide 35

Slide 35 text

Slide 36

Slide 36 text

Slide 37

Slide 37 text

Slide 38

Slide 38 text

Slide 39

Slide 39 text

Slide 40

Slide 40 text