I2C Tutorial for Renesas S5D9 board: Add ThreadX real time OS support. (Part 3)
Based on what is developed from Part 1 and Part 2.
Show how to use the powerful real time OS ThreadX to manage the run time for temperature reading and display update. The benefits of using ThreadX are removal of the complex and error-prone main loop code in Part 1 and 2 and easy change to the rate for display update and temperature measurement.
Configure Grove A port from UART to I2C.
Show how to set breakpoints for debugging the code with real time OS.
Show how to use RTOS profiling for resources information (such as stack requirement and utilization).
1. Renesas E2 Studio Tool version 5.4.0.023
2. Renesas SSP version 1.30
3. S5D9 IOT ENABLER pack file
1. I2c IIC Serial 128x64 Oled LCD Module (Amazon Link)
2. 4 Pin Female Jumper To Grove 4 Pin Conversion Cable (Amazon Link)
3. The Jlink debugger board (included in S3A7 kit)
1. E2 Studio Installation. For this tutorial, use E2 Studio version 5.4.0.023 and SSP version1.30. (IOT Community Link)
2. Blinky Example with E2 Studio and Jlink Flash (IOT Community Link)
4. C language coding skill.
1. Connect the OLED display to the J4 I2C grove B header of S5D9 board.
2. Connect the SHT31 temperature and humidity sensor to the J3 UART grove A header of S5D9 board. (We will use the e2 studio to reconfigure this port from UART to I2C.)
3. Connect the J-link debugger board to the J2 header of S5D9 board and USB port of your PC. This board is for uploading your code into the board. It is also used for e2 studio to debug your code.
4. Connect J9 to another USB port of your PC.
1. E2 Studio Project Setup
1.1 Synergy C Project
1.2 SSP 1.30
1.3 S5D9 IOT ENABLER board
2. E2 Studio Pin Configuration
2.1 IIC1 (P1_1/P1_0) is connected to J4 Grove B which we attach the OLED display module.
2.2 SCI0 (P4_11/P4_10) is connected to J3 Grove A which we attach the SHT 31 temperature sensor. Because P4_11/4_10 is part of an advanced SCI port, it can be configured as a simple UART, SPI, or I2C bus as desired. We will configure it as a I2C bus this time.
3. E2 Studio Thread Configuration
3.1 HAL / COMMON Thread (Default - automatically created)
3.2 System Thread : Created to set LED light setting in case of error occurrence.
3.3 SHT31 Thread : Sensirion Humidity and Temperature Sensor Measurement Thread
(SCI_spi master driver)
3.4 OLED SSD1306 : OLED SSD 1306 display driver Thread (IIC master driver)
Priority : System Thread > OLED SSD1306 Thread > SHT31 Thread
Note: System Thread is only for the LED's initialization, and it contains an empty while loop that does nothing. SHT31 Thread and OLED SSD1306 Thread runs all the times. OLED SSD 1306 Thread receives the temperature data from SHT31 Thread.
Using extern volatile <var type> <global variable name in the other thread enables the OLED SSD 1306 Thread to get the temperature value from the SHT31 Thread.
4. C code Files Comparison
1. hal_entry.c/h (Main Program Loop)
2. i2c.c/h (i2c SSP API calls)
3. SHT31.c/h (subroutines for SHT31 operations)
4. ssd1306_oled.c/h (subroutines for OLED module operations)
1. hal_entry.c (Empty now)
2. system_thread_entry.c/h (Setup LED for normal operation and warning purpose)
3. sht31_thread.c/h (SHT31.c/h + all the SHT31 related code in the old hal_entry.c + i2c.c)
3. oled_ssd1306_thread.c/h (all the oled ssd1306 related code in the old hal_entry.c)
4. ssd1306_oled.c/h (unchanged except for the iic driver name.)
Note: Separate threads for SHT31 and SSD1306 make pretty easy to insert delay to control the sampling rate of the operations such temperature reading or display update! A complex main loop is no longer needed to control the divided time between these two operations.
Code for Download
Download all the codes and a copy of the project file from my Github site. (Github repository link)
Step by Step Procedures
Project Creation Section
Step 1: Open E2 Studio and create a new C synergy project file.
Step 2: Enter Project name and click Next.
Step 3: Select 1.3.0 for the SSP version and S5D9_IOT_ENABLER for the board. Then click Next.
Step 4: Select BSP for the project template selection. Then click Next.
Step 5. Click Yes.
Step 6: This summary window will appear. Check the project information for correctness.
Pins Configuration Section
Step 7: Select the Pins tab. Select IIC1 (Grove B) under Connectivity:IIC. Just review the setting. P101 is assigned as SDA while P100 is asigned as SCL. You don't have to change anything her.
Step 8: Select SCI0 (Grove A) under Connectivity:SCI. Currently this SCI channel is configured for UART operation mode. We will change it to I2C.
Step 9: Select Simple I2C.
Step 10: Select P411 for SDA pin and P410 for SCL pin. That is all we will do for pin configuration.
Threads Configuration Section
Step 11: Select Threads tab. We will start to add new Thread. Click on the "+" icon. Under properties tab, update all the parameters inside the red box.
Step 12: In the SHT31 Thread Stacks window, click "+" icon to add I2C Master Driver r_sci_i2c". Note that there are two I2C driver types. Because SHT31 is connected to a port that is configured as a SCI port, we choose r_sci_i2c driver over r_iic driver.
Step 13: Fill in the parameter boxes within the red box. Here we enter the device slave address instead of inside the C code. Since it is SCI0, we choose channel 0.
Step 14: We will add another new Thread for OLED display. Click on the "+" icon. Under properties tab, update all the parameters inside the red box. We like to set a higher priority for OLED Display thread.
Step 15: In the OLED SSD 1306 Thread Stacks window, click "+" icon to add I2C Master Driver r_iic". Note that there are two I2C driver types. Unlike SHT31, the OLED display module is connected a port that is configured as a IIC port, we choose r_iic driver over r_sci_i2c driver.
Step 16: Fill in the parameter boxes within the red box. Here we enter the device slave address instead of inside the C code. Since it is IIC1, we choose channel 1.
Step 17 : We will add the last new Thread for the LED's setup. Click on the "+" icon. Under properties tab, update all the parameters inside the red box. We like to set the highest priority for this thread.
Source Code Section
Step 18: Press the Generate Project Content to create all the c and h files under the src folder. Copy all the files from my github repository into the src folder.
Compilation and Run Section
Step 19: Right click on the project name and select "Build Project."
Step 20: There should be no errors or warnings.
Step 21: Right click on the project name and then select "Debug As" --> "Debug Configurations..."
Step 22: Select "S5D9... Debug" and then press the "Debug" button.
Step 23: Press Yes!
Step 24: Press F8 two times. "Running" should appear on the bottom. The green LED on the S5D9 board should be turned on.
(Debugging Section) updated.
Step 25: For debugging, put the debug break point at any line by double click on the line. A tiny box icon should appear. Under the breakpoints tab, the break line details should appear.
After the code is suspended, use step into or step over in the icon toolbar to run the code line by line.
Updated on 2/18/2018: You can set the break point anywhere, not just line with tx_thread_delay function call.
Step 26: To profile threads, suspend the run and select RTOS resources tab. Click OK because we are using threadx OS.
Step 27: Resume (F6) and then Suspend. Select Threads tab. Now you see the details about the three threads.
Step 28: Select Stack tab. You can see that the tool calculates what the max slack (amount of RAM) required for each thread. If you are allocating less than the max slack, go back to the thread configuration and increase the slack RAM.
Conclusion and Challenge
Congratulation! Perhaps you can change the code to display the current humidity value instead of the current temperature value. Or, you can create a new thread for one of the on-board senors for your own application. Have fun!