8.1 Library Example Code

Example code is shown for most library functions. These examples illustrate how the functions can be called and might indicate other aspects of their usage, but they are not necessarily complete nor practical.

The examples can be run in a simulator, such as that in the MPLAB X IDE. Alternatively, they can be run on hardware, but they will require modification for the device and hardware setup that you are using. The device configuration bits, which are necessary for code to execute on hardware, are not shown in the examples, as these differ from device to device. If you are using the MPLAB X IDE, take advantage of its built-in tools to generate the code required to initialize the configuration bits, and which can be copied and pasted into your project's source. See the MPLAB® X IDE User’s Guide for a description and use of the Configuration Bits window.

Many of the library examples use the printf() function. Code in addition to that shown in the examples might be necessary to have this function print to a peripheral of your choice.

When the examples are run in the MPLAB X IDE simulator, the printf() function can be made to have its output sent to a USART (for some devices, this peripheral is called a UART) and shown in a window. To do this, you must:
  • Enable the USART IO feature in the MPLAB X IDE (the IDE might offer a choice of USARTs).
  • Ensure that your project code initializes and enables the same USART used by the IDE.
  • Ensure that your project code defines a 'print-byte' function that sends one byte to the relevant USART.
  • Ensure that the printf() function will call the relevant print-byte function.
Some compilers might provide generic code that will already implement the USART initialization and print-byte functions, as itemized above. For other tools, you can often use the Microchip Code Configurator (MCC) to generate this code. Check to see if the MCC is available for your target device. Even if it is not, you may be able to adapt the MCC output for a similar device. Typically, the default USART settings in the MCC will work with the simulator, but these may not suit your final application. Once the USART is configured, you may use any of the standard IO library functions that write to stdout, in addition to printf().

Some library examples might also use the scanf() function. Code in addition to that shown in the examples might be necessary to have this function read a peripheral of your choice.

When the examples are run in the MPLAB X IDE simulator, the scanf() function can be made to read from a USART that is taking input from a text file. To do this, you must:
  • Enable the USART IO feature in the MPLAB X IDE.
  • Ensure that your project code initializes and enables the same USART used by the IDE.
  • Ensure that your project code defines a 'read-byte' function that reads one byte from the relevant USART.
  • Ensure that the scanf() function will call the relevant read-byte function.
  • Provide a text file containing the required input, and have the content of this file passed by register injection to the receive register associated with the USART used by the IDE.
Some compilers might provide generic code that will already implement the USART initialization and read-byte functions, as itemized above. For other tools, you can often use the Microchip Code Configurator (MCC) to generate this code. Typically, the default USART settings that MCC uses will work with the simulator, but these may not suit your final application. Once the USART is configured, you may use any of the standard IO library functions that read from stdin, in addition to scanf().

For further information about the MPLAB X IDE, see the MPLAB® X IDE User’s Guide; for the MCC tool, see the MPLAB® Code Configurator v3.xx User's Guide.

Compiler-specific implementations of the above are discussed in more detail in the following sections.