LightRanger Tutorial - General Introduction To Click Device Setup

 Objective

In this project, we will go through the basic setup of how the LightRanger click on an MPLAB® Xpress Evaluation Board (PIC16F8855). These basic steps serve as an instruction manual on how to set up most click boards.

 Materials

Hardware Tools (Optional)

Tool About Purchase
Xpress-50px.png
MPLAB® Xpress
Development Board

Software Tools

Tool About Installers
Installation
Instructions
Windows Linux Mac OSX
MPLAB® Xpress
Cloud Integrated Development Environment

 Procedure

This project uses:

To follow along with these steps, you should open MPLAB Xpress and log in so that the MPLAB® Code Configurator (MCC) plugin can be utilized. You should see a screen similar to the one shown here to start.

ideImage2

1

Task 1

The MPLAB Xpress Development Board should be connected from the micro USB connector on the board to an available USB port on the host computer through a USB cable. Drivers should install successfully the first time the board is connected and may take a minute or so. The connection is shown in the image.

xpressimage2

2

Task 2: Create A New Project

Create a new project in MPLAB Xpress for a PIC16F1855 using the MPLAB Xpress Development Board. Instructions are below if this is your first project.

3

Task 3: Open MPLAB Code Configurator

Open MCC under the Tools > Embedded > MPLAB Xpress Code Configurator menu of MPLAB Xpress.

figure4.png

A window will appear showing three steps. If you need the latest version of Java you can click on step one. Otherwise, click on the step two button to open MCC.

figure4_1.png

A file will automatically download in your browser similar to the image shown. Click on that file to open it. This is a java application that will launch the MCC.

figure4_4.png

The process can take several seconds depending on your internet connection speed. Several windows may appear asking if you want to run the program. When the process is complete you will see a new screen appear, separate from the MPLAB Xpress IDE, that is the MCC control screen. In this screen, you can select:

  • peripherals for your project,
  • system setup for the oscillator and other configuration settings,
  • and input/output selections for your device.

When all of these are completed you can generate project code including a main.c file by clicking on the Generate button near the center top of the screen. All these generated files will be included in your MPLAB Xpress project.

figure4_3.png

4

Task 4: Import LightRanger Library

In the open MCC window, navigate to 'Device Resources'. The LightRanger library will be found under Mikro-E clicks > Sensors > LightRanger. Double-click on 'LightRanger' to add the module to the 'Project Resources'. If done correctly, your project window should look something like this.

lightRanger.png

Note: The Information tab gives you a description of your current device. It also provides a link to the MikroElektronika website. This website has more useful documentation and schematics about your device. The examples provided by MikroElektronika through their website are not compatible with the 8-bit devices. However, Xpress examples can be found on this website: http://mplabxpress.microchip.com/mplabcloud/example

We will be using the generated example for this tutorial. Navigate to this 'Configuration' tab to verify that the 'Generate Example' checkbox is checked.

generatedExample.png

5

Task 5: Import EUSART

For this example, the microcontroller will be printing sensor readings from the LightRanger through use of printf statements. Any time printf statements are used, the command prints across a serial communication protocol called UART. On the PIC16F18855, the peripheral is an enhanced UART called EUSART. This peripheral will need to be imported into the project. Navigate to the Device Resources window and expand the 'EUSART' tab. Double-click the EUSART peripheral to add it to the 'Project Resources'.

EUSART.png

Additionally, the 'Redirect STDIO to USART' box will need to be checked to allow printf statements to be used in the code. This is necessary in order to allow the compiler to use the standard I/O library. Without this box checked, printf statements will not compile correctly.

redirectIOSquare.PNG

6

Task 6: Configure Pin Manager

There are labels on each pin for every click board. These labels can be matched to the corresponding pins on the Xpress board. Use this matching technique to configure the correct pins in your pin manager for any click or development board that you are using.

clickWithPinsSquare.PNG

The LightRanger Sensor uses EN, INT, SCL, and SDA to operate. These labels can be seen on the pins of the click board. On the Xpress board, these pins are RB2, RC2, RC4, and RC3 respectively. In the Pin Manager, lock the corresponding labels to their respective pins. Additionally, RC0 is used for TX-USB communication on the PIC microcontroller. Therefore through locking RC0 to TX, EUSART output data from the PIC microcontroller will be sent over the USB connection to the computer. This data output can be viewed by using a terminal emulator. The Pin Manager should look like this when finished.

pinModule.png

Note: Pins are sometimes Auto-Generated incorrectly or backward. Always double check pins to ensure correctness. If a warning comes up when attempting to change pins, click a pin further away from the currently locked pin in the same row. You should see the previously locked pin now unlock.

7

Task 7: Generate

Click on the Generate button in MCC to create the appropriate header and source files.

generateSquare.PNG

Upon successful code generation, the Generation Completed notification should appear. Select OK to close window

generationComplete.png

New MCC generated source and header files should now be present in the Project window of the MPLAB Xpress IDE including a new main.c source file.

sourceFiles.png

8

Task 8: Explore The Example Function

Click on the LightRanger_Example.c file under the MCC 'Generated Files' tab. Scrolling to the bottom of this example, you should see an Example_ReadRange function which prints out the data from the LightRanger sensor.

#include "LightRanger_Example.h"
#include "LightRanger.h"
#include "mcc.h"
 
void Example_ReadRange(void){
     while(1){
         LR_StartRange(SINGLE_SHOT);
         __delay_ms(105);
         uint16_t als = LR_ReadRange();
         printf("Range is %d\r\n", als);
      }
}

Note: If you are ever unsure of what an example does, you can always come to your project’s MCC generated Example.c file to see exactly what code will run during the example. Through doing this, you will be able to know if additional peripherals will need to be imported through MCC in order to correctly run the example. In this case, the EUSART peripheral needed to be manually added.

9

Task 9: Include Header File

Navigate to your main.c file in your Project window and import your example header file.

#include "mcc_generated_files/mcc.h"
#include "mcc_generated_files/LightRanger_Example.h"

Note: As a rule of thumb, any time an MCC generated example is being run, the appropriate example.h file will need to be included in your main.c file to compile the project correctly. If the correct header file is not imported, you may receive an error mentioning "conflicting definitions for variable". Similar to the output shown below.

error.PNG

10

Task 10: Call Example Function

exampleCode.png

Note: Because our LightRanger_Example.c file has a while(1) loop within it, we can make our function call in our main file outside of the while(1) loop.

11

Task 11: Compile and Download

Compile and download the project HEX file by clicking the Make and Program Device button at the top of the MPLAB Xpress IDE.

downloadAndCompileSquare.PNG

Program the MPLAB Xpress board by dragging the project HEX file from the downloads section of the browser and dropping the file onto the XPRESS drive.

dragAndDropFinal

12

Task 12: Set Up Terminal Emulator

Open a terminal emulator program on the host computer and select the COM port associated with the MPLAB Xpress board. In this example, a free program called CoolTerm is used. The correct COM port for the USB connection between your Xpress board and computer will need to be selected. Verify that the 'Baudrate' is set to 9600.

comPortSquare.PNG

Note: The correct COM port may differ from that shown above. If you are unsure about which COM port to use, this information can be found in the computer’s Device Manager under the 'Ports' section.

 Results

Once communication is established, the terminal should display the text enclosed in the printf statement shown in LightRanger_Example.c. This sensor shows values of 0-255 depending on how close or far away an object is. Additional code was added to the Example.c file to get values in inches and centimeters. You should see the output in the terminal change as you put an object closer and further away from this sensor. Something like what is shown here.

resultsInches.PNG

 Analysis

This LightRanger device calculates distance by measuring the time of flight of an emitted proton. Through completion of this tutorial, it should now be possible to measure the distance to any object within a range of 10-20 centimeters.

 Conclusions

This project shows how to see the output of the LightRanger click board in a terminal window. However, these basic steps are the foundation of how to integrate any available click board. This is a good tutorial if you are running into issues with clicks or need help fixing click errors in your project.

© 2023 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.