7l00ia: getting started with usb pcdc and phid drivers · description: this guide provides...

LAB PROCEDURE

7L00IA: Getting Started with USB PCDC and PHID Drivers of 22

7L00IA: Getting Started with USB PCDC and PHID Drivers RX111

Description: This guide provides step-by-step instructions in getting started with the FIT Peripheral Communications

Devices Class (PCDC) Driver and the the FIT Peripheral Human Interface Device Class (PHID) Driver in new or existing e2studio projects that use a FIT BSP. You will create an e2studio sample application for each and add various code sections to them.

Lab Sections 1 Create a new USB PCDC project for the RPBRX111 .................................................................... 2 2 Add FIT Modules and files to the project ........................................................................................ 6 3 Coding the basic application ......................................................................................................... 10

4 Build, load, and debug the application .......................................................................................... 12 5 Create a new USB PHID project for the RPBRX111 .................................................................... 16

6 Add FIT Modules and files to the project ...................................................................................... 16 7 Coding the basic application ......................................................................................................... 19 8 Build, load, and debug the application .......................................................................................... 20 9 Appendix ...................................................................................................................................... 22

Lab Objectives 1. Add a FIT USB PCDC driver to a project. 2. Perform basic data output from an RX MCU

over USB to a PC based terminal emulator.

3. Add a FIT USB PHID driver to a project. 4. Simulate basic keyboard data output from an

RX MCU over USB to a PC based text window.

Skill Level Intermediate Programming in C

Time to Complete Lab 60 Minutes

Lab Materials Please verify you have the following materials at your lab station.

RPBRX111 2 USB to USB mini cables E2Studio Renesas RX Toolchain

LAB PROCEDURE


1 Create a new USB PCDC project for the RPBRX111

Overview: This procedure walks you through starting a brand new project to just learn how to perform basic transmission of data over the USB in PCDC mode. The project will use FIT modules to simplify the process. The knowledge you gain from this exercise should allow you to more easily add USB PCDC to your own existing project.

System State at end of this section: Data will be transmitted from the RPBRX111 board USB port to a PC in a virtual COM port protocol.

The PC displays the data in a terminal emulation program.

Procedural Steps:

Step 1.1 At your workstation, open e2Studio to the lab workspace, "C:\Workspace\7L00IA_USB_PCDC\". If e2studio opens to the welcome screen, proceed to the workbench view.

Step 1.2 Create a new C project using the menu path: File->New->C Project.

Step 1.3 A project creation wizard will open. Give the project a name of your choice (e.g.: my_usb_pcdc_application). . Select the other options as shown: Sample Project, and Renesas RXC Toolchain. Then click Next >.

LAB PROCEDURE


Step 1.4 Continue setting up the project with the wizard. Set the Debug Hardware to Segger JLink (RX). Select the target MCU as R5F51115AxFM (for the RPBRX111 board). Make sure the other options are as shown, then click Next >.

LAB PROCEDURE


Step 1.5 Click the "Use FIT Module" checkbox, then click “Next>”

All of the required FIT modules have already been added to your lab copy of e2studio. On your own system you could click the "Download FIT Modules" button to automatically add new FIT modules to e2studio from the Renesas software download website, making them available for new projects.

LAB PROCEDURE


Step 1.6 Click “Next>” through the next few wizard screens without making changes until you get to the Standard Header Files screen. Deselect the unused header file options as shown. Be sure that C99 is selected as the library configuration. Then click Finish.

LAB PROCEDURE


2 Add FIT Modules and files to the project

Now it is time to begin adding the FIT modules that will be used by your USB PCDC application. First, every FIT-based project will need a FIT compliant BSP (board support package). The BSP needs to be added to the project first when using the e2studio FIT plugin tool before adding other FIT modules, because they depend on it. We will add a predefined FIT BSP selected for the RPBRX111 used in this exercise. (A user with a custom target board would need to create a custom FIT BSP based on FIT guidelines.)

Step 2.1 Use the FIT plugin feature to add the BSP for the RPBRX111 board we are using for this exercise. Select File->New->Renesas Fit Module.

LAB PROCEDURE


Step 2.2 The FIT Module selector will open. Using the pulldowns, filter for the RX111 Group and the RPBRX111 Target Board, select the latest Board Support Package (should be 2.90), then click Finish to add it to the new project you created.

Step 2.3 A message alerts you that the includes and source locations are updated; click OK. The BSP files will be added to the project in a new folder called r_bsp. It will also add a path to the r_bsp folder to the project include paths. When it does this a window will appear showing the new paths. Click the Apply button and then click OK.

Step 2.4 A new r_config folder will have been added to the project. For the BSP it is necessary to manually copy a configuration file into this folder. Locate the r_bsp_config_reference.h file in the r_bsp->board->rpbrx111 folder and copy it to the r_config folder. Rename the copy in r_config to "r_bsp_config.h"

Step 2.5 In the r_bsp folder, locate the platform.h file and open it in the e2studio editor. Locate the line //#include "./board/rpbrx111/r_bsp.h" and delete the comment characters to enable the line. Comment out any other board bsp path that may have already enabled. Save the changes. The BSP is now ready to be used with the RPBRX111. After this you may close the platform.h file.

Step 2.6 Open the FIT Module selector again, and change the target board filter setting to "Any". Now, one at a time, add the USB basic mini driver and the USB Peripheral Communications Device Class driver to the project using the FIT Module selector as was done for the BSP module. As the USB FIT modules are selected to be added the required dependencies will be listed. Be sure that you have already installed the prerequisite modules before proceeding, and click OK.

LAB PROCEDURE


Step 2.7 Again, the project paths should be automatically updated for the newly added code. Confirm that this is done, click apply then OK.

(Note: you will need to reset the Target Board setting to Any again as you add each module)

LAB PROCEDURE


Step 2.8 The config files for these modules will have been automatically added to the config folder. There are certain customizations that may need to be made in the config files. In the project "r_config" folder, open file "r_usb_basic_mini_config.h", and be sure that the following setting is made by adding or removing the comments "//" as needed at or near lines 27, 28:

/* Set the USB mode. (The USB mode specified in the project file.) */

//#define USB_FUNCSEL_PP USB_HOST_PP

#define USB_FUNCSEL_PP USB_PERI_PP

Step 2.9 At this point the project is ready to add code for initializing and servicing the USB drivers, and for the main user application. The next section will guide you through adding this code to the new project you are creating now.

LAB PROCEDURE


3 Coding the basic application

A skeletal sample project has been created that contains the minimal code to get started. The sample project, "7L00IA_usb_pcdc_resources" contains a source folder, "src", with two files: "usb_pcdc_application.c", and "r_usb_pcdc_apl_descriptor.c".

"usb_pcdc_application.c" contains a main() function and a number of supporting functions that constitute a basic sample application. "r_usb_pcdc_apl_descriptor.c" contains USB PCDC class descriptor fields and is borrowed from the released example application code in application note R01AN2296EJ0100.

Step 3.1 In this lab we will skip the code creation portion of this exercise by just copying the two source files, described above, into this project's src folder. The "my_usb_pcdc_application.c" file will no longer be needed, so delete it. Then proceed to the next section, "Build, load, and debug the application".

Step 3.2 For details on usage of the various PCDC driver API functions you can refer to the R01AN2170EJ0101 PCDC driver app-note located in the ../r_usb_pcdc_mini/doc folder in your project.

Table 1 Functions used in the lab sample application

Function name Description

main () Initializes USB pins and PCDC driver. Main loop calls PCDC scheduler task, and calls user application.

usb_mcu_pin_init () Set up I/O pins for USB port mode

usb_cpu_target_init () a function inside the USB Basic code that Enables USB interrupts and sets priorities to some defaults. Undocumented.

usb_driver_init () Starts task CSTD; "common" basic USB low level task. Organizes several PCDC driver function calls related to initialization. Described in the PCDC driver app-note. Little information in the app-note. Just use this or call the functions in it in the order shown.

cdc_registration () Registration of peripheral Communications Devices Driver. Registers the addresses of resources, descriptors, and callbacks that will be used by the PCDC driver

usb_psmpl_LineCodingInitial() Sets the nominal serial UART emulation communication settings.

usb_psmpl_change_device_state() A callback function called by the PCDC driver at times to pass state change information to the application. A skeletal version is implemented in the sample. It is up to you to figure out how much of it you want to use. Add appropriate code to the various states as necessary to manage the flow of your application.

my_dummy_callback_function() An empty callback function defined to the specification in the R01AN2170EJ0101 PCDC driver app-note. Don't try to the parameters as defined because they won't work due to API bug.

When adding the CDC driver to your own application, use the source files provided in the sample application as a reference. The rest of this section will just deal with explanations of the purpose and use of the various parts of the sample code.

LAB PROCEDURE


However for PCDC API function calls that require a callback pointer this can be used if you don't really want to do anything in the callback.

cdc_read_complete() A user defined callback must be given when making calls to the R_usb_pcdc_ReceiveData () function. The PCDC driver will then call it to notify your application that the read has finished. It will pass a data structure to you that contains further state and result information in the first parameter. Don't try to use the second or third parameters due to bug (will be fixed in a later release). Use as shown in the lab sample.

cdc_write_complete() A user defined callback must be given when making calls to the R_usb_pcdc_SendData () function. The PCDC driver will then call it to notify your application that the transmit has finished. It will pass a data structure to you that contains further state and result information in the first parameter. Don't try to use the second or third parameters due to bug (will be fixed in a later release). Use as shown in the lab sample.

R_usb_cstd_Scheduler () Part of USB Basic Mini driver. This is the USB task . You need to call this regularly to keep the USB going. It should be called in a main task loop from your code.

R_usb_pstd_PcdTask () PCD task that must be called if the USB task scheduler has an event flagged.

R_usb_pcdc_Task () CDC task that must be called if the USB task scheduler has an event flagged.

R_usb_pcdc_ReceiveData() The PCDC driver API function for receiving data from host.

R_usb_pcdc_SendData() The PCDC driver API function for sending data to host.

my_pcdc_application () This is the user application code. It needs to run as a task under the main task loop, regularly returning control to the main loop so that the USB task scheduler gets a chance to run. In the sample code it just receives characters and retransmits them using the R_usb_pcdc_ReceiveData() and R_usb_pcdc_SendData() functions.

LAB PROCEDURE


4 Build, load, and debug the application

Step 4.1 Build the code by clicking Project >> Build Project, or click the hammer icon.

Step 4.2 Verify the build completes and that ‘Build Complete’ is shown in the ‘Console’.

Step 4.3 Verify that the JLink debugger is connected to the PC by a USB cable. The JLink connector is the USB mini type connector on the bottom of the board.

Step 4.4 Start a debug session by right clicking on the project and choosing Debug As >> Renesas GDB Hardware Launch.

Step 4.5 Once the perspective has been changed you can start running the application by either clicking the Resume

button or clicking Run >> Resume. If execution stops at the beginning of the main() function click Resume again to continue.

Step 4.6 With the code running, connect a USB cable from the PC to the USB port on the top side of the RPB board. The PC will attempt to enumerate the USB connection, however no manufacturer specific CDC COM port driver has been installed. You will install the driver at this time.

Step 4.7 Open the Device Manager for your workstation (right-click Computer->Properties->Device Manager). In the device manager locate the entry that lists "CDC USB Demonstration". The PC has gotten this string from the descriptor data in your project's code.

Step 4.8 Double click the CDC USB Demonstration entry to open its properties window. Click the "Update Driver" button, then "Browse" for the driver to "C:\Workspaces\7L00IA" and click next. The driver is installed using the "CDC_Demo_Win7.inf" file. A Windows security message may warn that the driver software is not verified; Click "Install this driver software anyway".

LAB PROCEDURE


Step 4.9 Wait for the driver to finish installing, and then close the installation and properties windows. Now check the Device Manager window again. The warning for CDC USB Demonstration should be gone and instead a new COM port device will be listed under "Ports (COM & LPT).

Step 4.10 Make note of the COM port number assigned to the CDC USB Demonstration device, in this case (COM12).

Step 4.11 Open the "Tera Term" application on the PC. If the "New Connection" dialog does not automatically appear, then select File-> New Connection. Click the serial option and select the COM port from the pulldown that matches the device name that the PCDC enumerated under, e.g.: COM12: CDC USB Demonstration.

Step 4.12 The terminal window should appear with a blank screen. Begin typing into the terminal screen and observe the results.

The installation of the CDC driver will only be needed the first time it is used.

LAB PROCEDURE


Step 4.13 Disconnect the device USB cable (not the debugger), close the Tera Term application, and stop the debug session in e2studio.

Change the Descriptor Product ID When you connect the device to the host USB port the host will attempt to 'enumerate' the device to identify the drivers it needs to use the device. To do this it examines values contained in the device descriptor that was sent to the host from the device at connection time. Two of the key identity fields are the Vendor ID (VID) and the Product ID (PID). The VID is assigned by the USB organization, and the PID is the vendor's own choice. In this demo we are using a dummy VID of 0, and a PID of 2 by default. In your own commercial product you would need to customize these descriptor values. You are now going to make some simple edits to learn where this is done.

Step 4.14 In file "r_usb_pcdc_apl_descriptor.c", located in the project src folder, change the value for USB_PRODUCTID from 0x0002u to 0x0003u like this:

#define USB_PRODUCTID (0x0003u) /* Product ID */

Step 4.15 Rebuild the project and then download and run it under the debugger as described previously in this section.

Step 4.16 Re-connect the USB to the host PC and wait for the host to recognize the device.

When typing characters into the terminal window the characters you will see are not echoed locally by the terminal itself. What you type is first sent to your USB CDC application on the target board. The data is then sent back to the terminal application over USB. What you are seeing displayed is the data sent by your application!

Questions 1. What PCDC API function would you call to receive characters from the terminal?

2. What PCDC API function would you call to send characters to the terminal?

3. Where in the project code is the "CDC USB Demonstration" string found?

Question 4. Did the PC recognize your USB device?

LAB PROCEDURE


Step 4.17 Open the Device Manager again, navigate to the "CDC USB Demonstration" entry, and double-click it to open its properties window. Select the "Details" tab then select "Hardware Ids" from the Property pull-down list. Observe that the PID value is 0003 -- the value you just changed to in the project's device descriptor.

Step 4.18 The host needs to match the PID with one found in its loaded drivers. You can edit the corresponding PID value in the .inf file you loaded earlier to match the new PID:

Open "C:\Workspaces\7L00IA\CDC_Demo_Win7.inf" in the editor and find the entries:

[DeviceList]

%DESCRIPTION%=DriverInstall, USB\VID_0000&PID_0002

[DeviceList.NTamd64]

%DESCRIPTION%=DriverInstall, USB\VID_0000&PID_0002

Step 4.19 Change the values for PID to match the PID value in the project descriptor; i.e.: PID_0003 and save the file.

Step 4.20 Go back to the "General" tab in the CDC USB Demonstration properties window. Click the "Update Driver" button, then browse to "C:\Workspaces\7L00IA" and click next. The driver is re-installed using the newly edited "CDC_Demo_Win7.inf" file. A Windows security message may warn that the driver software is not verified; Click "Install this driver software anyway".

Optional Challenge (try later if you have time): Try modifying your project code to take a character received from the terminal, perform a simple operation based on it, then send the result back to the terminal. For example, multiply a numerical value and return the product. To do this you will need to locate the recived data in the transfer buffer after it is received, then place the result data back into the buffer for transmission. Your output data will need to be formatted as ASCII characters to print on the terminal window. Modify the data length parameter as needed. Data reception and transmission is done in the sample code "my_pcdc_application()" function using the PCDC API functions R_usb_pcdc_ReceiveData() and

R_usb_pcdc_SendData() .

End of Section

LAB PROCEDURE


5 Create a new USB PHID project for the RPBRX111

Overview: This exercise is very much like the first except that it uses the USB PHID class instead of PCDC. This exercise walks you through starting a brand new project that introduces how to perform basic transmission of data over the USB in PHID mode. Again, the project will use FIT modules to simplify the process. The knowledge you gain from this exercise should allow you to more easily add USB PHID support to your own new or existing project.

System State at end of this section: Data will be transmitted from the RPBRX111 board USB port to a PC using the HID keyboard device class.

A string of characters will be entered into an open text entry window as though being typed in from a keyboard.

Procedural Steps:

Step 5.1 Create a new C project using the menu path: File->New->C Project.

Step 5.2 A project creation wizard will open. Give the project a name of your choice (e.g.: my_usb_phid_application). Select the other options as shown: Sample Project, and Renesas RXC Toolchain. Then click Next >.

Step 5.3 Continue setting up the project with the wizard. Set the Debug Hardware to Segger JLink (RX). Select the target MCU as R5F51115AxFM (for the RPBRX111 board). Make sure the other options are as shown, then click Next >.

Step 5.4 Click the "Use FIT Module" checkbox, then click “Next>”

Step 5.5 Click “Next>” through the next few wizard screens without making changes until you get to the Standard Header Files screen. Deselect the unused header file options as shown. Select C99 as the library configuration. Then click Finish.

6 Add FIT Modules and files to the project

Add the FIT BSP

Step 6.1 Use the FIT plugin feature to add the BSP for the RPBRX111 board we are using for this exercise. Select File->New->Renesas Fit Module.

Step 6.2 The FIT Module selector will open. Using the pulldowns, filter for the RX111 and the RPBRX111, select the latest Board Support Package, then click Finish to add it to the new project you created.

Step 6.3 The BSP files will be added to the project in a new folder called r_bsp. It will also add a path to the r_bsp folder to the project include paths. When it does this a window will appear showing the new paths. Click the Apply button and then click OK.

Step 6.4 A new r_config folder will have been added to the project. For the BSP it is necessary to manually copy a configuration file into this folder. Locate the r_bsp_config_reference.h file in the r_bsp->board->rpbrx111 folder and copy it to the r_config folder. Rename the copy in r_config to "r_bsp_config.h"

Step 6.5 In the r_bsp folder, locate the platform.h file and open it in the e2studio editor. Locate the line //#include "./board/rpbrx111/r_bsp.h" and delete the comment characters to enable the line. Comment out any other board bsp path that may have already enabled. Save the changes. The BSP is now ready to be used with the RPBRX111. After this you may close the platform.h file.

LAB PROCEDURE


Step 6.6 Open the FIT Module selector again, and change the target board filter setting to "Any". Now, one at a time, add the USB basic mini driver and the USB Peripheral Human Interface Device Class driver to the project using the FIT Module selector as was done for the BSP module. As the USB FIT modules are selected to be added the required dependencies will be listed. Be sure that you have already installed the prerequisite modules before proceeding, and click OK

LAB PROCEDURE


Step 6.7 Again, the project paths should be automatically updated for the newly added code. Confirm that this is done, click apply then OK.

Step 6.8 The config files for these modules will have been automatically added to the config folder. There are certain customizations that will need to be made in the config files. In the project "r_config" folder, open file "r_usb_basic_mini_config.h", and be sure that the following setting is made by adding or removing the comments "//" as needed at or near lines 27, 28:

/* Set the USB mode. (The USB mode specified in the project file.) */

//#define USB_FUNCSEL_PP USB_HOST_PP

#define USB_FUNCSEL_PP USB_PERI_PP.

Step 6.9 Open "r_config/r_usb_phid_mini_config.h" in the editor and configure the build mode for keyboard device by uncommenting the line:

#define USB_PHID_MODE USB_PHID_KEYBOARD_MODE /* PHID keyboard mode */

At the same time comment out the mouse mode line:

// #define USB_PHID_MODE USB_PHID_MOUSE_MODE /* PHID mouse mode */

Step 6.10 In the same file, around lines 57, 58, disable the usb_gphid_dummy_ReportDiscriptor and enable the

usb_gphid_ReportDiscriptor definition as follows:

// #define USB_REPORT_DISCRIPTOR usb_gphid_dummy_ReportDiscriptor;

#define USB_REPORT_DISCRIPTOR usb_gphid_ReportDiscriptor;

Step 6.11 At this point the project is ready to add code for initializing and servicing the USB drivers, and for the main user application. The next section will guide you through adding this code to the project you are creating now.

LAB PROCEDURE


7 Coding the basic application

A basic sample project has been created that contains the minimal code to get started. The sample project, "7L00IA_usb_phid_resources" contains a source folder, "src", with three files: "usb_phid_application.c", "r_usb_phid_descriptor.c", and "r_usb_phid_apl.h".

"usb_phid_application.c" contains a main() function and a number of supporting functions that constitute a basic sample application. "r_usb_phid_descriptor.c" contains USB PHID class descriptor fields that will be used to set this application up as a HID "keyboard" device. It is borrowed from the released example application code in application note R01AN2297EJ0101.

Step 7.1 In this lab we will skip the code creation portion of this exercise by just copying the three source files, described above, into this project's src folder. The "my_usb_phid_application.c" file will no longer be needed, so delete it. Then proceed to the next section "Build, load, and debug the application"

Step 7.2 For details on usage of the various PHID driver API functions refer to the application note: "USB Peripheral Human Interface Device Class Driver for USB Mini Firmware Using Firmware Integration Technology R01AN2171EJ0101.

Function name Description

main () Initializes USB pins and PHID driver. Main loop calls PCDC scheduler task, and calls user application.

usb_mcu_pin_init () Set up I/O pins for USB port

usb_cpu_target_init () a function inside the USB Basic code that Enables USB interrupts and sets priorities to some defaults. Undocumented.

usb_driver_init () Starts task CSTD; "common" basic USB low level task. Organizes several PHID driver function calls related to initialization. Described in the PHID driver app-note. Little information in the app-note. Just use this or call the functions in it in the order shown.

hid_registration () Registration of peripheral Human Interface Device driver. Registers the addresses of resources, descriptors, and callbacks that will be used by the PHID driver

R_usb_phid_ChangeDeviceState() Call from the user application to change the device’s USB state.

hid_write_complete() A user-defined callback must be given when making calls to the R_usb_phid_send_data() function. The PHID driver will then call it to notify your application that the transmit has finished.

When adding the USB PHID driver to your own application, use the source files provided in the sample application as a reference. The rest of this section will just deal with explanations of the purpose and use of the various parts of the sample code.

LAB PROCEDURE


R_usb_cstd_Scheduler () Part of USB Basic Mini driver. This is the USB task scheduler. You need to call this regularly to keep the USB going. It should be called in a main task loop from your code.

R_usb_pstd_PcdTask () PCD task that must be called if the USB task scheduler has an event flagged.

R_usb_phid_task HID task that must be called if the USB task scheduler has an event flagged.

my_phid_application () This is the user HID application code. It needs to run as a task under the main task loop, periodically returning control to the main loop so that the USB task scheduler gets a chance to run. In the sample code it just periodically writes out a simple test string to the USB using the R_usb_phid_send_data() function.

8 Build, load, and debug the application

Step 8.1 First be sure that the head of your PCDC project is selected in the the Project Explorer view, then build the code by clicking Project >> Build Project, or click the hammer icon.

Step 8.2 Verify the build completes and that ‘Build Complete’ is shown in the ‘Console’.

Step 8.3 Start a debug session by right clicking on the project and choosing Debug As >> Renesas GDB Hardware Launch.

Step 8.4 Once the perspective has been changed you can start running the application by either clicking the Resume

button or clicking Run >> Resume. If execution stops at the beginning of the main() function click Resume again to continue.

Step 8.5 Open the Notepad application on the PC and be sure that the Notepad window is highlighted.

Step 8.6 While your code is running on the debugger, connect a USB cable from the PC to the USB port on the RPB board. The PC should enumerate the USB connection as a HID class device. If this is the first time doing so, a message may appear on the PC that it is adding new hardware.

Step 8.7 As soon as your USB HID device has registered with the PC you should see text being entered into the Notepad text area

LAB PROCEDURE


Question 5. What will happen if you change the focus to another window with text entry capability while this is running?

LAB PROCEDURE


9 Appendix

Answer To Questions:

1. What PCDC API function would you call to receive characters from the terminal? R_usb_pcdc_ReceiveData()

2. What PCDC API function would you call to send characters to the terminal? R_usb_pcdc_SendData()

3. Where in the project code is the "CDC USB Demonstration" string found? r_usb_pcdc_apl_descriptor.c

4. Did the PC recognize your USB device? Should not

5. What will happen if you change the focus to another window with text entry capability while this is running? Text will be input to any open window that accepts text, just as if typed from a keyboard.

7l00ia: getting started with usb pcdc and phid drivers · description: this guide provides...

Documents