At one point or another, every developer has struggled to get a software module to work the way that they expect it to. Modern microcontrollers have graduated from the simple little 8-bitters into complex, feature rich 32-bit devices. We’ve all seen microcontroller datasheets that easily top two-thousand pages and are just warming up. Digging through and finding what is needed to initialize a peripheral can be daunting let alone if a single bit gets overlooked. In this post, we will walk through a new type of application note that makes it easier to develop with the Synergy Platform and the SSP Module Guides. In this blog we will explain how to use module guides and how they can greatly simplify the developers coding life.
The new module guides have been developed to help improve the speed and efficiency at which developers can get a module up and running along with understanding how the module works. The guides are organized in such a way that they make it easy to find important information about the module, such as:
In order to help the reader fully understand the Module Guide, we are going to walk through each section and discuss how it helps the developer. To do this efficiently, let’s examine a recently posted Module Guide for the AGT HAL Module. You can find the full module guide and follow along with this post here.
The first informational section of every module guide is similar in content to that shown for the AGT HAL Module in Figure 1. It includes a short list of the key features and a block diagram of the ‘stack’ the module uses within SSP. This information should allow the developer to understand if the module implements the functions needed in the target application.
Following the overview information is a table of the available APIs. An example from the AGT module guide is shown in Figure 2 below. The API table includes the API name, an example API call, and a short description of the API function- enough information to get started using the APIs in an application. (Only the first few API calls are shown in the example. Review the Module Guide for the full list). Following the API table is a table of status return codes, making it easier to implement post call processing.
Figure 2: API Description Table and Status Return Values Table
After the API descriptions and status return values the module guides provide an operational overview. This overview highlights the key operations supported by the module and identifies important details needed to use the module in a target design. Often hardware considerations, such as clocking, interrupts and operating modes are explained in this section.
Figure 3: AGT HAL Module Operational Overview
At this point the developer has a significant amount of background information to efficiently use the module in a typical design. But wait! There’s more! Often there are additional operational notes and limitations that are important for the developer to understand prior to using the module. The module guide includes this information in the sections that follow the Operational Overview. Figure 4 below shows an example of this information for the AGT HAL Module.
Figure 4: AGT HAL Module Operational Notes and Limitations
The next section of the module guide describes the process used to add a module to a project. It shows the stack selection sequence and the resulting stack in the configuration window of the ISDE. Some stacks require additional configuration and this is explained in this section.
Figure 5: Adding the AGT HAL Module to an Application
Each module typically has a variety of configuration properties available to customize the operation for a target application. This information is provided in a table within this section of the module guide. As seen in the example in Figure 6 below, the configuration parameter, available values, a short description helps augment the information available in the ISDE. (Note that the below figure only shows the first few configuration settings. See the Module Guide for the entire list).
Figure 6: Configuration Settings for the AGT HAL Module
In addition to the configuration settings the developer needs to understand how to select clocking options and pin assignments. This information is available in this section of the module guide, as illustrated in the AGT HAL module example shown in Figure 7 below.
Figure 7: Module Guide Clock and Pin Selection Information
Now that all the background information has been described, the module guide provides a simple example of a typical use case for how the application might use the module. The section has a short description, a list of typical steps for using the module and a flow chart showing the sequence of API use.
Figure 8: Module Guide Typical Application Use
All this background information is very helpful in understanding module features and how to use it, but you may have noticed there are no code snippets or examples-just API examples and a flow chart. Where is the code?
Renesas decided that rather than putting code snippets through-out the text document, which tends to not be beneficial to developers at all, that it’s better to provide an actual SSP project that is easy to ‘copy and paste’ into a developer’s own project. A complete, working project is a much better starting point and removes copy/paste and build errors that developers always encounter when trying to translate an example into a project. The remainder of the module guide provides a description, walk through and all the details of the included working project. The next blog will describe the project and how the remaining sections of the module guide augment the project to further accelerate development.
Until next time,
Live long and profit!
Hot Tip of the Week
Each module guide has its own resources article in the Renesas Synergy Knowledge Base. This makes it easy to stay up to date on the most recent examples, issues and information associated with the module. Simply search the Knowledge Base for the Module you are interested in. For example, if you are looking for the resources for the r_agt module, visit https://en-us.knowledgebase.renesas.com/English_Content/Renesas_Synergy%E2%84%A2_Platform/Renesas_Synergy_Knowledge_Base and enter “r_agt module guide resources” in the search bar. The search will bring up a list of results, and the top one will be the resources page for that module guide. The below url will take you directly to the search results for the example.