“Hello World” using the UART Application Framework

Serial communications are a critical piece to nearly every embedded system. Whether developers are using UART, SPI, IIC or USB, developers need a way for their systems to communicate with the external world. Traditionally the first communication test is to print “Hello World” through the desired interface and onto a terminal. In this post, we will explore the Renesas Synergy™ UART Application Framework and walk through the necessary steps to get it up and running on a SK-S7G2 starter kit and say “Hello World!”.

The UART Application Framework abstracts out the low level hardware and MCU registers, allowing developers to get UART communications up and running in minutes rather than days. Adding the UART Application Framework to a project is quite simple. Starting from a clean project configured by the Synergy wizard to be a Blinky project with ThreadX, a developer can open the Synergy configuration file and navigate to the threads tab. After selecting the blinky thread, a thread stack can be added by selecting add Framework -> Connectivity -> Communications Framework on sf_uart_comms stack as seen below.

Once the developer has added the UART Application Framework to the project, there are a few configuration items that need to be handled. First, within the SCI module properties, the Asynchronous Mode (r_sci_uart) needs to be enabled. The g_uart0 UART Driver on r_sci_uart module will still be colored red, indicating that further configuration is required. Clicking on the module, the four interrupts associated with SCI RXI, TXI, TEI and ERI all need to have their priorities set. For an example, we can set these to Priority 6. Saving the changes results in the configuration being accepted (the red coloring now becomes black) and our development environment will look similar to the image below.

By default, the UART Driver on r_sci_uart module is configured for 9600 bps, 8 bits, 1 stop bit which is pretty standard. Developers can change these defaults from the properties tab if necessary. Once the desired settings have been entered, save all changes and then press the “Generate Project Content” button before rebuilding the project. The hooks for the UART Application Framework will now be added to the application.

At this point, the UART Application Framework is configured and ready to be utilized in the project. If a developer has never used the Synergy Software Package (SSP) before, they may be wondering how they can now use this powerful framework that is included in the project. The trick for getting the API’s associated with the framework is to use the framework name instance, in this case g_sf_comms0 (see the thread stack image above), and then examine its p_api member which in the IDE will reveal all available API calls. So in English, or computer code more accurately, typing g_sf_comms0.p_api-> in the IDE will reveal the following:

Perusing the API calls, while keeping a “Hello World” application in mind, a developer should notice that the open and write API’s are immediately of interest. The entire specification for the API calls are listed there as well! No need to traverse a 2000-page datasheet looking for the right register or call. The information is right at a developers’ finger tips within the development environment.

Writing the “Hello World” application using the UART Application Framework requires only four lines of code. From within the blinky_thread_entry function located in blinky_thread_entry.c, two definitions are required:

   ssp_err_t ReturnVal;

   uint8_t Message[] = "Hello World!\n\r";

ReturnVal is used determine whether the port opening and data writes were successful or not. The Message array holds the string that we want to print out the UART. In order to receive output in a terminal that is nicely formatted, we use the newline (\n) and return (\r) characters at the strings end.

The next step, is to open the communication port. In order to do this, we need to pass a control and a configuration object into the open API function. The g_sf_comms0 object that we created in the threads stack already contains these objects. The properties that we changed, such as setting the UART to UART0 are already configured for us so there is no need to create any specialized objects. Instead, we make a very simple call to open and pass the g_sf_comms0 p_pctrl and p_cfg pointers into the function as follows:

   ReturnVal = g_sf_comms0.p_api->open(g_sf_comms0.p_ctrl, g_sf_comms0.p_cfg);

The communication port should be opened within blinky_thread_entry function before entering the threads while loop. The reason is that we only want to open the port once and not every time the thread executes. Instead, we want to make sure that the write function is called each time the thread executes so that we see “Hello World” printed on our terminal. Writing data to the UART through the Application Framework is straightforward. The write function requires the p_ctrl pointer for our UART, a pointer to the message we want to transmit, how many bytes to transmit and then a timeout for writing the data. The blinky_thread_entry thread can be modified to print “Hello World” as follows:

At this point, all the code is now setup to send “Hello World” out UART0; However, there are a few adjustments that would need to be made depending on the hardware that is being used in order to receive the message. As an example, we’ll now look at these required changes in order to receive “Hello World” using the SK-S7G2 starter kit.

There are multiple ways a developer could get access to the UART0 TXD and RXD on the SK-S7G2 board. The first, is to use the PMODB output port. A quick look through the SK-S7G2 user manual reveals that TXD0 and RXD0 are located on PMODB pins 3 and 5 respectively, shown below.

An alternative, would be to use the Arduino headers located on connector J27 pins 1 and 2. Using the Arduino headers would require us to change from UART0 to UART2. A very minor and simple change that would be made from within the framework stacks properties. The pin locations can be seen in the lower right hand side image below.

Finally, a third option would be to use the pin headers that break-out every pin on the S7G2 processor. For this example, we’ll use this option but all three options are perfectly valid. A developer at this point would use a UART to USB adapter, such as a Sparkfun USB to Serial board (https://www.sparkfun.com/products/12731) to access the TXD and RXD pins. Note that a ground connection is also required which is readily available on the SK-S7G2 break-outs.

With the USB to Serial adapter in place, if a developer were to run the application at this point, having a terminal such as PuTTy open, they would discover that they receive no output. Major bummer. As it turns out, the reason for the silent output is that the TXD0 and RXD0 pins are configured for SPI communication by default. In the Synergy configuration file, open the pins tab and observe the options on the left hand side. The options include ports, peripherals, analog pins and other. Expanding the peripherals option reveals the different peripherals that can be configured on the target including a SCI0_2_4_6_8 option. Expanding this option and clicking on the SCI0 peripheral opens on the right hand side a configuration window. (Alternatively the filter could be used to find SCI0). By default, the SCI0 is configured for SPI. Using the Operation Mode dropdown, selecting Asynchronous UART (RXD/TXD) will change the pin behavior to UART. The project can then be regenerated and compiled.

Executing the sample program at this point now reveals the following output:

Success! The UART Application Framework is now properly configured on the development kit and communicating with the external world. Not only was this simple to achieve but scaling into far more complex applications is just as straightforward.

Next time we will expand on this example and dig into the Console Application Framework and see how quickly and easily we can get it up and running.

Live long and profit!

Professor_IoT

Hot Tip of the Week

Check out the new web camera application project now available showing Parallel Data Capture (PDC) with JPEG hardware encode, and image streaming via an HTTP web server. This project targets the DK-S7G2 kit and the included camera module. The PDF project description is available here:

https://www.renesas.com/en-us/doc/products/renesas-synergy/apn/r12an0046eu0100-synergy-pdc-camera.pdf

The project is available here:

https://www.renesas.com/en-us/software/D6000201.html